caspac

The caspac utility can be used to administer a PAC.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

caspac -a{action}=object -p{pacName} -s{store} -n{psorName}

Parameters:

-p

Specifies the PAC name to use, if not specified then the value of the ES_PAC environment variable will be used.

-a

Specifies the action to perform and the object it will be performed on.

action

The following actions support PAC administration:

InitPac

Initializes the PAC ready for a cold start. Forcing the PAC to initialize will remove all information from the PSOR. This option is must only be applied if all the regions in the specified PAC have been stopped.

Status

Provides the current status for the PAC.

Dump

Creates a dump file of the SOR that have been created for the specified PAC.

Note: The filename created by the caspac Dump action are different, they do not include the endpoint but instead the text _coh_, the extension remains .rdmp.

Restore

Restores a dump file into the specified Scale-Out Repository (SOR).

PacLog

Creates a log file for messages generated by the PAC using the specified SOR.

SetMode

The specified work mode can be:

Running: Sets the work mode flag in the specified PSOR so that batch workload and EXEC CICS START are enabled to be processed.
Quiesce: Sets the work mode flag in the specified PSOR to prevent batch workload and EXEC CICS START from being processed.

CheckCompat

Use this to check the compatibility of the current installed enterprise server instance version against the specified PSOR if it was created using a different version. The following or similar message will be displayed if it is incompatible along with a -1 return code:

Located an incompatible CSA record in the PSOR, a compatible upgrade is not possible.

RemOldPAC

Enables you to remove a PAC stores (PSOR) created pror to Visual COBOL 7.0 PU8 that are not prefixed with a PAC name.

RemShrQueues

Deletes all stores called Shared_CasTSQ_RC, Shared_CasTSQ_NR, Shared_CasTDQ_RC, and Shared_CasTDQ_NR that are introduced in Visual COBOL 8.0 and that enables you to share TS and TD between PACs using the new ESCWA option when defining a SOR.

The following actions support recovery:

CasDEQs="file_path\file_name.csv": Use this to list all errors that might have occurred on DEQs either at the END of Task or while a Job or Transaction was executing.
This action generates a CSV file that can be used to manually recover the DEQs using dbfhadmin commands.
RecoverUUID: Specifying the UUID of the enterprise server region that left the PAC will remove all entries related to that enterprise server region from the PSOR.
RecoverLostUUID: This enables you to recover all enterprise server regions on a specified hostname that might have lost their connection to the PSOR, or that have been killed by the user.

The following actions support program deployment:

Delete

Deletes a loaded file from the SOR.

List

Lists the user programs that have been loaded into the SOR.

Load

Loads and deploys a non CICS or JES object as soon as the caspac command is issued. The object is deployed into the PAC_LOADLIB folder of the region's workarea.

LoadCics

Loads an object ready to be deployed into CICS when you execute the CPMT NE command. The object is deployed into the PAC_LOADLIB_CICS folder of the region workarea.

LoadJes

Load an object and deploy it directly into the PAC_LOADLIB_JES folder of the region workarea

object

Specifies the object the action is to use and can take one of the following values depending on the action being taken:

DLL
Share Object
PAC Name
Dump File
PAC Log File

Note: The object name is case-sensitive.

Retrieve

Retrieves binaries loaded in the SOR, such as CICS or JES objects. Specify the matching criteria using the asterisk "*" wildcard. You can include a -o parameter to specify an output folder. The output filename will be determined by the name of the objects retrived from the SOR.

-ssor

Specifies the SOR type and its connection parameters.

Note: Redis and Oracle Coherence have different connection parameters. See PAC and SOR Environment Variables for more information.

To connect to a Redis SOR, for example:

redis,127.0.0.1:6741

To connect to a Coherence SOR, for example:

coherence,mfes-cache-config.xml,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1:7574

-n{psorName}

Name of the PAC SOR. This is only required for Redis AUTH authentication requests or Redis SENTINEL. See Providing Credentials for Redis using Secrets for more information.

When using Redis AUTH you will need to create a secret in the vault facility for each PSOR that is used as a reference using the -n option.

-p{PACName}

The PAC name to use, if this is not specified the PAC name is taken from the ES_PAC environment variable. The PSOR is prefixed by the PAC name and a version number enabling you to run multiple PACs from the same PSOR, this can assist with performing an incompatible upgrade process.

Comments:

From Visual COBOL 8.0, the PSOR stores are prefixed by the PAC name and a version number enabling you to run multiple PACs in the same PSOR, this simplifies the incompatible upgrade process.

The caspac utility enables you to add the PAC name as part of the command line parameters using -pPACName or if not specified using the ES_PAC environment variable.

Examples

The following example loads acct.dll into the SOR represented by the Redis server located at 127.0.0.1 on port 6741. The acct.dll can then be deployed to all active enterprise server instances in the PAC using the New Copy command:
```
caspac -pMyPAC -aLoadCics="c:\new files\acct.dll" -sredis,127.0.0.1:6741 -npsorName
```
The following example loads all files under c:\new files into the SOR represented by the Redis server located at 127.0.0.1 on port 6741. Because this is for JES, a new copy command is not required:
```
caspac -pMyPAC -aLoadJes="c:\new files\*.*" -sredis,127.0.0.1:6741 -npsorName
```
The following example loads all non CICS and JES files under c:\new files into the SOR represented by the Redis server located at 127.0.0.1 on port 6741:
```
caspac -pMyPAC -aLoad="c:\new files\*.*" -sredis,127.0.0.1:6741 -npsorName
```
The following example removes acct.dll from the SOR represented by the Redis server located at 127.0.0.1 on port 6741:
```
caspac -pMyPAC -aDelete=acct.dll -sredis,127.0.0.1:6741 -npsorName
```
The following example lists user programs that have been uploaded into the SOR:
```
caspac -pMyPAC -aList=* -sredis,127.0.0.1:6741 -npsorName
```
The following example initializes the PAC called MyPAC ready for a cold start. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aInitPac=MyPAC -sredis,127.0.0.1:6741 -npsorName
```
Alternatively, the following example uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:
```
caspac -aInitPac=MyPAC -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
```
The following example returns the status of the PAC called MyPAC. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aStatus=MyPAC -sredis,127.0.0.1:6741 -npsorName
```
Alternatively, the following example returns the status of the PAC that uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:
```
caspac -aStatus=MyPAC -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
```
The following example creates a dump of the PAC called MyPAC. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aDump=MyPAC -sredis,127.0.0.1:6741 -npsorName
```
Alternatively, the following example creates a dump of the PAC that uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:
```
caspac -aDump=MyPAC -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
```
The following example restores a PAC from a the CasPAC_127.0.0.1_06741.rdmp dump file. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aRestore=CasPAC_127.0.0.1_06741.rdmp -sredis,127.0.0.1:6741 -npsorName
```
The following example restores a PAC from a dump file that matches the use of the * wildcard. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aRestore=*.rdmp -sredis,127.0.0.1:6741 -npsorName
```
Alternatively, the following example restores a PAC from a dump file that matches the use of the * wildcard. The PAC has a PSOR that uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:
```
caspac -aRestore=*.rdmp -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MYPAC_cluster=127.0.0.1
```
The following example writes a PAC log file to the folder and file specified. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aPacLog="c:\temp\PacLog.log" -sredis,127.0.0.1:6741 -npsorName
```
Alternatively, the following example writes a PAC log file to the folder and file specified from a PSOR that uses Oracle Coherence and has a cluster called MyPAC_cluster located at 127.0.0.1:
```
caspac -aPacLog=/tmp/paclog.log -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
```
The following example checks the compatibility of the specified PAC with the PSOR that uses Redis server located at 127.0.0.1 on port 6741:
```
caspac -aCheckCompat=MyPAC -sredis,127.0.0.1:6741
```
The following example sets the PAC to running mode or normal operating mode. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aSetMode=Running -sredis,127.0.0.1:6741 -npsorName
```
The following example places the PAC in Quiesce mode. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
```
caspac -aSetMode=Quiesce -sredis,127.0.0.1:6741 -npsorName
```
The following example exports a .csv file that contains a list of the DEQ errors for the Redis server located at 127.0.0.1 on port 6741:
```
caspac -pMyPAC -aCasDEQs="c:\temp\DEQ_report.csv" -sredis,127.0.0.1:6741 -npsorName
```
The following example will remove entries from the PSOR corresponds to the UUID specified for the Redis server located at 127.0.0.1 on port 6741:
```
caspac -pMyPAC -aRecoverUUID=1059443BD0330489609618E90F76B91B -sredis,127.0.0.1:6741 -npsorName
```
The following example removes all PSOR entries for MyPAC from the Redis server located at 127.0.0.1 on port 6741 for stores that where not prefixed:
```
caspac -aRemOldPAC=MyPAC -sredis,127.0.0.1:6741 –npsorName
```
The following example removes all the Shared_CasTSQ_RC, Shared_CasTSQ_NR, Shared_CasTDQ_RC, and Shared_CasTDQ_NR stores from the Redis server located at 127.0.0.1 on port 6741:
```
caspac -aRemShrQueues -sredis,127.0.0.1:6741 -npsorName
```
The following example will recover all regions on the hostname which is a member of the PAC called MyPAC and which has a Redis server located at 127.0.0.1 on port 6741:
```
caspac -pMyPAC -aRecoverLostUUID=hostname -sredis,127.0.0.1:6741 -npsorName
```
The following example will retrieve a CICS DLL file from the Redis server located at 127.0.0.1 on port 6741 from a named PSOR and output it to the folder specified by the -o parameter:
```
caspac -pMyPAC -aRetrieve=CICS@acct.dll -sredis,127.0.0.1:6741 -npsorName -o"c:\folder"
```