T40.3: %buildccr Functions

Overview

When code is deployed across multiple CCR environments (BASE, TEST, UAT, LIVE), there are situations where the behavior of that code needs to differ depending on which environment it is running in. Rather than maintaining separate versions of code for each environment, InterSystems provides a set of built-in functions in the %buildccr routine. These functions allow a single codebase to query the current environment at runtime and adjust its behavior accordingly.

Because the same source code is deployed identically to every environment via ItemSet transport, the %buildccr functions are the recommended way to introduce environment-specific behavior without breaking the principle of identical code across environments.

$$IsLIVE^%buildccr

This function returns a boolean value indicating whether the current environment is LIVE. It is commonly used to prevent certain actions from occurring outside the production environment.

Typical use case: Prevent emails from being sent to actual users from BASE or TEST environments. For example, a business operation that sends notification emails can check $$IsLIVE^%buildccr and redirect emails to a developer mailbox when not in LIVE, ensuring that test messages never reach end users.

If $$IsLIVE^%buildccr {
    // Send email to actual recipients
    Set tTo = tRealRecipient
} Else {
    // Redirect to developer mailbox
    Set tTo = "dev-team@example.com"
}

$$Env^%buildccr

This function returns the environment type as a string: "BASE", "TEST", "UAT", or "LIVE". It is useful when code needs to distinguish between all environment tiers rather than just checking for LIVE.

Typical use case: Display the environment in email footers, UI headers, or log output so that users and administrators can immediately identify which environment generated a message or report.

Set tEnv = $$Env^%buildccr
Set tFooter = "This message was sent from the ["_tEnv_"] environment."

$$EnvName^%buildccr

This function returns the specific environment name configured in the CCR system. Unlike $$Env^%buildccr which returns the environment type (BASE, TEST, etc.), $$EnvName^%buildccr returns the actual name assigned to the environment, such as "TRAIN" or "QA-WEST".

Typical use case: Perform customized logic for specific named environments. For example, a TRAIN environment that serves as a peer to TEST may need slightly different behavior from the primary TEST environment.

Set tEnvName = $$EnvName^%buildccr
If tEnvName = "TRAIN" {
    // Special logic for training environment
}

$$Sys^%buildccr

This function returns the SystemCode for the current environment. The SystemCode identifies which CCR system the environment belongs to.

Typical use case: Include the SystemCode in error logs so that when issues are reported, administrators can immediately identify which system generated the error. This is especially valuable in organizations that manage multiple CCR systems.

Set tSys = $$Sys^%buildccr
$$$LOGINFO("Error occurred in system: "_tSys)

$$Org^%buildccr

This function returns the organization code for the current environment. The organization code identifies the customer or organizational entity associated with the environment.

Typical use case: Include organization details in email alerts sent to a centralized monitoring system. When a monitoring team oversees multiple organizations, the organization code helps them route alerts to the correct support team.

Set tOrg = $$Org^%buildccr
Set tSubject = "["_tOrg_"] Alert: Interface error detected"

Using %buildccr Functions with Configure^%buildccr

The %buildccr routine also provides the Configure^%buildccr entry point, which is used for interactive configuration of the CCR client tools on each environment. Running Do Configure^%buildccr in the terminal launches a wizard that configures the source control hooks, including settings like whether to decompose productions. The $$ functions described above read the configuration values that are set during this configuration process, so they return accurate results on every environment where CCR client tools have been properly configured.

Summary of All %buildccr Functions

Function	Returns	Example Use Case
$$IsLIVE^%buildccr	Boolean (is LIVE?)	Suppress emails in non-LIVE
$$Env^%buildccr	Environment type (BASE, TEST, UAT, LIVE)	Display in email footers and UI headers
$$EnvName^%buildccr	Environment name (e.g., TRAIN)	Logic for named peer environments
$$Sys^%buildccr	SystemCode	Include in error logs
$$Org^%buildccr	Organization code	Route alerts in centralized monitoring

Best Practices

• Use %buildccr functions instead of hardcoded environment checks: Do not compare hostnames or IP addresses to determine the environment. The %buildccr functions are the officially supported mechanism.
• Combine with System Default Settings: For configuration values like file paths and IP addresses, prefer System Default Settings. Reserve %buildccr functions for logic-level branching where code behavior itself must change.
• Test in all environments: Because the functions return different values in each environment, ensure that the code paths for each environment type are exercised during testing.
• Use in ImplementCCR routines: The %buildccr functions can be used inside ImplementCCR routines (e.g., ImplementCCR.BEST0001) to perform environment-specific setup during ItemSet deployment.
• Do not call %buildccr functions at compile time: These functions should be called at runtime, not in class parameters or compile-time expressions, because the values are environment-specific and the code is compiled in BASE before deployment.

---