Customization information for REXX

This section provides customizing information. It should be reviewed prior to performing the steps listed in Step 1--Modify your RDO definitions to add required entries. It covers the following topics:

Changing supplied CICS transaction codes

There are three transaction ids supplied by the product. They are: REXX, EDIT, and FLST. You can change these supplied transaction ids.

The functions of REXX, EDIT, and FLST

The functions of REXX, EDIT, and FLST are:

REXX
is the default transaction id. When the REXX exec ends, control is returned to CICS®.
EDIT
is the transaction id associated with the REXX Development System editor. When the EDIT session ends, control is returned to CICS.
FLST
is the transaction id associated with the REXX Development System file list exec, CICFLST. When the FLST session ends, control is returned to CICS.

Changing the supplied transaction ids

You can change the names of the supplied transaction ids, and you can add additional transactions which will call your own execs.

RFS filepool definitions

The supplied member, CICVSAM in CICSTS31.REXX.SCICJCL, creates the VSAM data sets for two RFS filepools. The names for these VSAM data sets can be changed to match your installation standards. If you do change these names make sure to make matching changes to the member, CICRDOD, as well. Since the RDO definitions supplied contain the data set names, DD statements are not needed in the CICS startup job. This technique can be used to add additional files to an RFS pool or to add additional RFS filepools without restarting your CICS system.

The FILEPOOL DEFINE commands in member, CICSTART in data set CICSTS31.REXX.SCICEXEC have two purposes. The first is to define the names of the supplied filepools. They are: POOL1 and POOL2. You can modify these names to your installation standards. They can be from 1 to 8 characters. They should not contain special characters, ":" or "\". The second purpose is to associate the filepool ids to the FCT definitions for the VSAM data set used for its directory and the first VSAM file used for data storage.

If you want to add additional RFS filepools to your system you need to add RDO definitions and add FILEPOOL DEFINE commands to your CICSTART member. If you intend to allow users to add RFS files to the new filepool you must define the filepool to include a \USERS directory.

To make these new filepools available for use, you must restart CICS. However, you can also add filepools while your CICS system is active as follows.

TD queues needed for IMPORT and EXPORT commands

The REXX Development System uses dynamic allocation to IMPORT members from a partitioned data set or to EXPORT RFS files to a partitioned data set. The member CICRDOD in data set CICSTS31.REXX.SCICJCL defines three Transient Data entries used as input for IMPORT and 3 Transient Data entries for output for EXPORT. This allows three users to concurrently IMPORT and three users to concurrently EXPORT from and to partitioned data sets.

Modify the number of TDQ entries to suit your needs, but you should allow for at least one input and one output entry. The TDQUEUE NAME must begin with REX and be suffixed with a valid character. Ensure there are no other applications using TDQUEUE names that begin with REX because IMPORT/EXPORT will use them and may cause files to become corrupted.

SQL definitions used for authorizing transactions to use DB2

The member CICRDOD in data set CICSTS31.REXX.SCICJCL authorizes the transactions, REXX, EDIT, FLST, and DXB0 to use the DB2® plan. The first three of these transactions are REXX for CICS transactions and the DXB0 transaction is added if you have OfficeVision/MVS and want to use DB2 interface calls which may run under the OV/MVS transaction id. If you choose to modify the supplied transactions for the REXX Development System, you need to modify the DB2 entry definitions also.

If you implement new transactions which use the DB2 interface code then you should also add these DB2 entry definitions to your RDO group.

Special exec data sets used by the REXX Development System

There are three data set concatenations which are used by the REXX Development System which have no FCT entries. They are the DD names, CICCMDS, CICEXEC, and CICUSER. These data sets are partitioned data sets and are accessed using MVS™ facilities.

CICCMDS
The CICCMDS DD name concatenation should start by referencing the data set CICSTS31.REXX.SCICCMDS. This data set contains those execs which implement REXX Development System authorized commands. Only authorized users or execs authorized to use authorized commands may access these execs. If you choose to extend the REXX Development System with your own authorized commands, you should concatenate your data set to this DD name concatenation.
CICEXEC
The CICEXEC DD name concatenation should start by referencing the data set CICSTS31.REXX.SCICEXEC. This data set contains those execs which are supplied by the REXX Development System that use authorized commands. If you choose to extend the REXX Development System with your own execs which use authorized commands then you should concatenate your data set to this DD name concatenation.
CICUSER
The CICUSER DD name concatenation should start by referencing the data set CICSTS31.REXX.SCICUSER. This data set contains those execs which are supplied by the REXX Development System that do not use authorized commands. If you choose to extend the REXX Development System with your own execs which do not use authorized commands then you should concatenate your data set to this DD name concatenation.

The facilities used to access these data set concatenations use CICS WAIT EXTERNAL capabilities to avoid placing the CICS region into a wait.

Special USER ids and their usage

It is recommended that external security be used in the CICS environment. This is needed because individual user's information is maintained by the REXX Development System by the user's userid designation. Each user should have his own identification and there should not be two users signed on to the REXX Development System with the same userid at the same time. Two users with the same userid operating at the same time could have unusual results.

If a user is not signed on to the CICS region then the special userid of "*RCUSER*" is used to access the RLS and RFS facilities.

Authorized users are identified to the REXX Development System through the AUTHUSER command. This command is an authorized command and can only be used by an authorized user or an exec which is authorized to use authorized commands. CICSTART is such an exec because it resides in the CICEXEC DD name concatenation.

The member, CICSTART in the supplied data set CICSTS31.REXX.SCICEXEC then should be modified to contain an AUTHUSER statement to identify at least one userid which should be an authorized user. It is important to add the AUTHUSER statement after the existing AUTHUSER statement for RCUSER. For example:

        'AUTHUSER RCUSER'
           IF RC ¬= 0 THEN EXIT RC 
        'AUTHUSER your-userid'
           IF RC ¬= 0 THEN EXIT RC 

You could also call another exec of your choosing, within the CICEXEC concatenation, which could contain the userids of those users who should be authorized users.

Other considerations

The member, CICSTART in data set CICSTS31.REXX.SCICEXEC, contains default definitions for the REXX Development System. It is executed when the first user who executes a transaction that uses the CICREXD program after the CICS system has been started. This exec should be updated with any changes in customization if those changes are required to be effective across CICS executions.

The REXX Development System provides the capability to execute execs in either pseudo-conversational or conversational mode. The system default for conversational mode is specified with the SETSYS PSEUDO statement in the member, CICSTART in the data set CICSTS31.REXX.SCICEXEC. The default supplied provides for pseudo-conversational to be used. CICSTART must run in conversational mode because the system has not yet been initialized enough to ensure correct operation.

The CICSTART member also contains EXECLOAD commands which are commented as shipped. EXECLOADing execs will reduce the amount of storage used by the REXX Development System because users will then share the same exec. Also performance may be increased because these execs will not have to be loaded into CICS memory each time they are executed. EXECLOADed execs are used before any other execs. Therefore, if you EXECLOAD an exec "TEST.EXEC" and you have an exec in your RFS current directory by the same name, you will not be able to execute your RFS copy. Care should then be used both in the naming or your execs and EXECLOADing them. The authorization associated with the special DD names is maintained when execs are EXECLOADed from those DD name concatenation.

Online HELP facility

An online HELP facility is provided which may be used as an example of the REXX/CICS panel facility. It provides the means to search and display the LIST3270 manual which is supplied with the product. There are several steps which must be done in order to activate the online help.

Note:
If PTF maintenance has been applied that affects data sets for the procedure outlined below, then you should use the target library; otherwise, the distribution library should be used.

First, modify member CICSTART in the data set CICSTS31.REXX.SCICEXEC to reflect the correct RFS filepool and path where the online help files should be. If you choose to use the default no changes to CICSTART are necessary.

Next copy the supplied data set CICSTS31.REXX.SCICDOC to a data set whose highest level data set qualifier matches the userid of the user who will be executing the CICHPREP exec. The reason for this is the supplied security exit for the REXX/CICS IMPORT and EXPORT commands checks the highest level qualifier and it must match the userid for the user who issues the IMPORT command.

Next copy the supplied data set CICSTS31.REXX.SCICPNL to a data set whose highest level data set qualifier matches the userid of the user who will be executing the CICHPREP exec. This data set contains the panel definitions which are used by the online help. They must be IMPORTed into the RFS filepool and path defined for the online help.

Next sign onto REXX/CICS using the REXX transaction id. If you have changed the default transactions, this is the transaction id associated with the CICRXTRY exec. Issue the command, 'EXEC CICHPREP'. Follow the instructions issued by the exec. This exec will reads the LIST3270 format of the manual from the data set you name, into the RFS directory specified in CICSTART. It also splits the manual into multiple files for usage by the online help. Additionally, the panels used by the online help are IMPORTed into the RFS system.

The online HELP facility is now ready for use.

There are several ways the user may access the online HELP.

Enter 'HELP' on the command line from the interactive environment and a table of contents is displayed. You also may enter this command from the command line of the REXX/CICS editor or the REXX/CICS filelist facilities.

Entering 'HELP xxxxx' searches the INDEX of the manual for the xxxxx entry. If found you are taken directly to that section of the manual.

There also is a HELP key defined for the editor and the filelist facility. It is defined in the customizing macros for the editor and the filelist facilities. The supplied default for this key is PF1. You may choose to modify the supplied default by modifying these profiles.

[[ Contents Previous Page | Next Page Index ]]