Space announcement This documentation space provides the same content as before, but the organization of the content has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Task 3.2: Implementing the BMC PARMLIB

Starting with release 17.02, BMC AMI mainframe products, including Xchange, use parameter libraries (PARMLIBs) in conjunction with the BMC AMI Common Mainframe Services Controller (CMSC) to configure each product as well as common components. The CMSC was installed as part of the BMC AMI Enterprise Common Components installation. For more information on the on the parameter libraries, see PARMLIB-members.

The default parameters that need to be specified in the Xchange CMSC PARMLIB member reside in member XCHG00 in the CPWR.MLXGnnn.SLXGDATA library.

In this task, you will implement the BMC PARMLIB for Xchange. This consists of creating a default member and updating the CMSC with it. The sample member is suffixed with 00 and should contain the values you want for the system on which Xchange is installed. This task is necessary for both a new installation and an upgrade of Xchange to release 17.02.

Important

Whenever you modify an existing BMC PARMLIB member or add a new member, you will need to use the CMSC REFRESH command to update the contents of the CMSC cache.


Task 3.2.1: Create the default member

Copy the associated member from the Xchange CPWR.MLXGnnn.SLXGDATA library members into your BMC PARMLIB data set. The SLXGDATA library members are set up for the most common settings.


Task 3.2.2: Specify Xchange parameters

The Xchange CMSC PARMLIB member name must be prefixed with XCHG and suffixed with either the CMSC default suffix or 1 to 4 characters of your choice. If suffixed with anything other than the default, make sure the suffix matches the SUFFIX= value on the PARM of the EXEC JCL statement in the Xchange startup JCL.

Important

Commonly used and user-defined parameters are described in this Task. Descriptions of all other parameters are provided in the User-Guide.

PARMLIB Syntax Rules for Xchange

When editing an Xchange PARMLIB member, the following guidelines must be observed:

  • All data is case sensitive.
  • Each entry is to be coded as a KEYWORD=value format.
  • Any characters in columns 73 through 80 are ignored.
  • The Data-Area containing the KEYWORD=value information is columns 1 through 71, unless it is extended by a continuation.
  • Placing a + character in column 72 denotes a continuation. The Data-Area is extended by 71 bytes by appending columns 1 through 71 of the following record to the end of the Data-Area.
  • An asterisk (*) in column 1 denotes a comment record:
    • A comment record cannot be continued.
    • All data on a comment record is ignored.
  • Keywords are all upper case.
  • The equality sign (=) must immediately follow the keyword.
  • The value associated with the keyword begins immediately following the equality sign (=).
  • Value termination rules:
    • If the first character of the value is a single-quote ('), the string is terminated by the last single-quote in the Data-Area.
    • Otherwise, if the first character of the value is a double-quote ("), the string is terminated by the last double-quote in the Data-Area.
    • Otherwise, if a space exists in the Data-Area, the value is terminated with the character immediately preceding the first space in the Data-Area.
    • Otherwise, the value is terminated with the last byte of the Data-Area.
  • Data following the last byte of the value in the Data-Area is ignored.

Saving the CMSC PARMLIB Member and Refreshing

After adding the default parameters and modifying those parameters based on your organizational needs, save the Xchange CMSC PARMLIB member. Don't forget to enter the CMSC REFRESH command (see Task 3.2: Implement the BMC PARMLIB). The CMSC REFRESH command must be issued every time changes are made to the Xchange CMSC PARMLIB member. In addition, the Xchange subsystem must be recycled for the changes to take effect. 

Xchange parameters

Essential Xchange parameter keywords, values, and defaults are defined as follows. Other parameters are described in the User-Guide.

SUBSYS

A four-character value that defines the subsystem ID for the Xchange program using this configuration. This value must be unique within the entire MVS complex. The subsystem ID used for a previous Xchange installation cannot be reused without performing an IPL. We recommend consulting an MVS system programmer to choose a name that does not duplicate any existing MVS subsystem names. The default is CWXG.

Important

  • Xchange dynamically creates this subsystem in the SSCVT. Do not add the subsystem to IEFSSNxx. No modification of SYS1.PARMLIB is required for installation, except to authorize the AUTHLIB load library.
  • The first Xchange subsystem started creates another subsystem named XGPC that is shared by any subsequent Xchange subsystems. The name XGPC is reserved for this Xchange subsystem and should not be used for any other subsystem.

DMPPFX

A one- to twelve-character prefix used on all dump data sets that Xchange dynamically allocates. The default is CWXGDUMP.

Important

The prefix you specify must conform to the rules for coding a data set name. Do not end the prefix with a period (.). The period will be added when the data set is created. If more than eight characters are used, a period (.) must be inserted to create two levels of the data set qualifier. The 12-character maximum includes the period. You must ensure that your external security system gives all userIDs authority to create new dump data sets that are named using the prefix you specify.

SECPFX

A one- to eight-character name that the external security module uses as a prefix when creating entity names to pass to the security system. The default is CWXG. For information on external security see Milestone-8-Configuring-Xchange-external-security.

DEFINE_JOURNALS and END Block Parameters

Important

If you choose to have a journal or journal data sets, DEFINE_JOURNALS, the block start parameter, must immediately precede the first related block LOGxxxx parameter, and the END block end parameter must immediately follow the last one.

Use the LOGxxxx parameters to define each journal data set used by the Xchange subsystem. There is no limit to the number of journal data sets that a single Xchange subsystem can use. You can define as few or as many as you like, but you must specify one LOGDDN, LOGDSN, and LOGCOPY parameter for each journal data set.

Each journal data set must have been defined by IDCAMS, and there cannot be JCL statements in the Xchange job referring to these data sets. Xchange dynamically allocates each data set and, in turn, de-allocates each data set when it is filled. This process allows automatic or manual unloading of data from inactive journal data sets.

The JCL statements used to create your journal data sets reside in the installation library CPWR.MLXGnnn.SLXGCNTL file member ALLOCLOG. Make a note of the journal file names you use in this macro so you can enter them accurately in the ALLOCLOG JCL deck in Allocate the Journal Data sets.

If you intend to view or extract records from the journal, specify at least two journal files. This permits automatic swapping from a filled journal file to the next journal file. When each journal file is swapped out, the next file is reset when it is swapped in, and data in it is lost. Therefore, more journal files give you more flexibility in monitoring Xchange transactions, but they require space allocated for the files themselves.

Important

Discuss the intended usage of Xchange with your site's users to determine optimal values for the LOGxxxx parameters.

DEFINE_JOURNALS

Block start parameter to identify the beginning of related parameters that define each journal data set used by the Xchange subsystem. This parameter must precede any LOGxxxx parameters.

LOGDDN

The one- to eight-character name of the data definition (DD) statement that Xchange uses when referencing this journal data set.

LOGDSN

The 1- to 44-character data set (DS) name for this journal data set.

LOGCOPY

Whether the journal data set is the backup journal file. Each time a journal file is filled, all date records are copied from that file to the backup journal file and appended to the existing entries in that backup file. YES indicates that the journal file is the backup file. NO indicates that it is not. Only one LOGCOPY parameter can contain the YES value. The default is NO.

END

Block end statement for DEFINE_JOURNALS parameter block. This parameter must immediately follow any LOGxxxx parameters.

Important

The parameters prefixed with LOG above must be in the order listed for each journal data set. For example, if using multiple journal data sets, the parameters would be listed in the following order.

DEFINE_JOURNALS
LOGDDN=JOURNAL1
LOGDSN=CUSTOMER.JOURNAL1
LOGCOPY=NO
LOGDDN=JOURNAL2
LOGDSN=CUSTOMER.JOURNAL2
LOGCOPY=NO
etc.
END

PREVDATE

Whether previous dates are allowed (that is, whether a date can be exchanged for a date previous to the current date). The default is NO.

Important

For Execution Date requests, PREVDATE controls only whether a request can be set for a date previous to the current date.

REPLY

Whether an outstanding reply message will display on the operator console. The default is NO.

Important

The console operator can always enter Xchange commands with the MVS MODIFY and STOP commands.

RESTREQ

The restore requests parameter used to control the Xchange save and restore process during startup and normal processing of the Xchange address space. Valid values are WARM, COLD, and OFF.

Specifying WARM will cause Xchange to restore requests saved from its previous run. All requests are restored unless Xchange configuration changes, such as a reduction in XREs, prevent the restore. Jobclass, COPE Logical System, and CICS H requests are restored with the same first-use running date/time as when they were saved. The default is WARM.

Specifying COLD will cause Xchange to bypass restore processing during startup and delete any requests in the save/restore file. This option can be used to bypass restore processing if the file becomes damaged or to delete all current Xchange requests.

Requests created after Xchange is started with RESTREQ=COLD are still saved, however, and can be used at the next Xchange startup if the value of RESTREQ is subsequently changed to WARM.

Setting this RESTREQ to OFF will cause Xchange to bypass all save and restore processing. If your site uses the OFF setting, the XGSAV001 DD statement can be deleted from the XGSTART JCL or Xchange startup process.


Task 3.2.3: Update the CMSC with your PARMLIB members

Use the z/OS MODIFY (F) command to update the CMSC with the PARMLIB members you created.

Refreshing All PARMLIB Members

F cmscname,PARMLIB REFRESH

Refreshing a Single Parameter Member

F cmscname,PARMLIB REFRESH member_name

Important

During the refresh process, parameter values are validated. If they are found to be invalid, an error message is written to the FDBDLOG SYSOUT data set associated with the ECC CMSC instance where the member is being refreshed. If an error is detected, the contents of the in-core member will not be refreshed. You must correct the error and refresh the member before attempting to use it.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*