The CICS-supplied default autoinstall program is an assembler-language command-level program, named DFHZATDX. The source of the default program is provided in COBOL, PL/I, and C, as well as in assembler language. The names of the supplied programs and their associated copy books, and the CICSTS31.CICS libraries in which they can be found, are summarized in Table 28. Note that the COBOL, PL/I, and C copy books each have an alias of DFHTCUDS.
Language | Member name | Alias | Library |
---|---|---|---|
Programs:
Assembler COBOL PL/I C |
DFHZATDX DFHZCTDX DFHZPTDX DFHZDTDX |
None None None None |
SDFHSAMP SDFHSAMP SDFHSAMP SDFHSAMP |
Copy books:
Assembler COBOL PL/I C |
DFHTCUDS DFHTCUDO DFHTCUDP DFHTCUDH |
None DFHTCUDS DFHTCUDS DFHTCUDS |
SDFHMAC SDFHCOB SDFHPL1 SDFHC370 |
The module generated from the assembler-language source program is part of the pregenerated library shipped in CICSTS31.CICS.SDFHLOAD. You can use it without modification, or you can customize it according to your own requirements. If you choose to alter the code in the sample program, take a copy of the sample and modify it. After modification, use the DFHEITAL procedure to translate, assemble, and link-edit your module. Then put the load module into a user library that is concatenated before CICSTS31.CICS.SDFHLOAD in the DFHRPL statement. (This method applies to completely new modules as well as modified sample modules.) For more guidance information about this procedure, refer to the CICS® Application Programming Guide. Do not overwrite the sample with your customized module, because subsequent service may overwrite your module. You must install a new resource definition for a customized user program.
The default action of the sample program, on INSTALL, is to select the first model in the list, and derive the terminal identifier from the last four nonblank characters of the NETNAME, set the status byte, and return to CICS. If there are no models in the list, it returns with no action.
The default action, on DELETE, is to address the passed parameter list, and return to CICS with no action.
You can customize the sample program to carry out any processing that suits your installation. Examples of customization are given in Customizing the sample program. Generally, your user program could:
Here are three pieces of code that customize the sample program.
Figure 31, in assembler language, limits logon to netnames L77A and L77B. The model names utilized are known in advance. A logon request from any other terminal, or a request for a model which cannot be found, is rejected.
* REGISTER CONVENTIONS = *
* R0 used by DFHEICAL expansion *
* R1 -------"-------"------"---- *
* R2 Base for Input parameters *
* R3 Base for code addressability *
* R4 Base for model name list *
* R5 Base for output parameter list *
* R6 Work register *
* R7 -----"------- *
* R8 -----"------- *
* R9 free *
* R10 Internal subroutine linkage return *
* R11 Base for EIB *
* R12 free *
* R13 Base for dynamic storage *
* R14 used by DFHEICAL expansion *
* R15 -------"-------"------"---- *
*
* SELECT MODEL
*
LH R6,TABLEN Number of valid netnames
LA R7,TABLE Address the table
*
LOOP1 CLC NETNAME(4),0(R7) Is this netname in table?
BE VALIDT
*
LA R7,16(R7) Next table entry
BCT R6,LOOP1
*
* Now we know its not a valid netname
* simply return and the logon is rejected
*
B RETURN
*
* R7 now points to model name
VALIDT CLI SELECTED_MODELNAME,C' ' MTS model name supplied?
BNE VALIDM1 Yes
LH R6,MODELNAME_COUNT Count of models
LTR R6,R6 Were any presented?
BZ RETURN No
LA R8,MODELNAME First model name
*
LOOP2 CLC 8(8,R7),0(R8) Is this model name here?
BE VALIDM
*
LA R8,L'MODELNAME(R8) Next model name
BCT R6,LOOP2
*
* Now we know the required model name was not presented
* to this exit by CICS, a return rejects the logon
*
B RETURN
*
* At this point the model name was found in those presented
* It is given to CICS and the new termid is
* the netname
*
VALIDM MVC SELECTED_MODELNAME,0(R8) R8 was left pointing at
* model name
VALIDM1 DS 0H
MVC SELECTED_TERM_ID,NETNAME Use netname for termid
* (4 chars)
*
*
* SELECTIONS COMPLETE, RETURN
*
MVI SELECTED_RETURN_CODE,X'00' Indicate all OK
B RETURN Exit program
*
* Table of netnames allowed to log on and the model name
* necessary for the logon to be successful
*
* Format of table :
* Bytes 1 to 8 Netname allowed to log on
* 9 to 16 Model required for netname
*
DS 0D
TABLE DC CL8'L77A',CL8'3270064'
DC CL8'L77B',CL8'3270065'
TABLEN DC Y((*-TABLE)/16)
*
Figure 32, in COBOL, redefines the NETNAME, so that the last four characters are used to select a more suitable model than that selected in the sample control program.
.
*
* Redefine the netname so that the last 4 characters (of 7)
* can be used to select the autoinstall model to be used.
*
* The netnames to be supplied are known to be of the form:
*
* HVMXNNN
*
* HVM is the prefix
* X is the system name
* NNN is the address of the terminal
*
01 NETNAME-BITS.
02 FIRST-CHRS PIC X(3).
02 NEXT-CHRS.
03 NODE-LETTER PIC X(1).
03 NODE-ADDRESS PIC X(3).
02 LAST-CHR PIC X(1).
.
.
PROCEDURE DIVISION.
.
.
*
* Select the autoinstall model to be used according to the
* node letter (see above). The models to be used are user
* defined.
*
* (It is assumed that the netname supplied in the commarea by CICS
* has been moved to NETNAME-BITS).
*
* If the node letter is C then use model AUTO2
* If the terminal netname is HVMC289 (a special case) then use
* model AUTO1.
* Otherwise (node letters A,B,D...) use model AUTO3.
*
IF NODE-LETTER = 'C' THEN MOVE 'AUTO2' TO SELECTED-MODELNAME.
IF NEXT-CHRS = 'C289' THEN MOVE 'AUTO1' TO SELECTED-MODELNAME.
IF NODE-LETTER = 'A' THEN MOVE 'AUTO3' TO SELECTED-MODELNAME.
IF NODE-LETTER = 'B' THEN MOVE 'AUTO3' TO SELECTED-MODELNAME.
IF NODE-LETTER = 'D' THEN MOVE 'AUTO3' TO SELECTED-MODELNAME.
.
.
Figure 33, in PL/I, extracts information from the VTAM® CINIT RU, which carries the BIND image. Part of this information is the screen presentation services information, such as the default screen size and alternate screen size. The alternate screen size is used to determine the model of terminal that is requesting logon. The presented models are searched for a match, and if there is no match, the first model from those presented is used.
DCL 1 CINIT BASED(INSTALL_CINIT_PTR),
2 CINIT_LENG FIXED BIN(15),
2 CINIT_RU CHAR(256);
DCL SAVE_CINIT CHAR(256);
/* Temp save area for CINIT RU */
DCL 1 SCRNSZ BASED(ADDR(SAVE_CINIT)),
2 SPARE CHAR(31),
/* Bypass first part of CINIT and reach */
/* into BIND image carried in CINIT */
2 DHGT BIT(8),
/* Screen default height in BIND PS area */
2 DWID BIT(8),
/* Screen default width in BIND PS area */
2 AHGT BIT(8),
/* Screen alternate height in BIND PS area */
2 AWID BIT(8);
/* Screen alternate width in BIND PS area */
DCL NAME CHAR(2);
/* Used to work up a screen model type */
DCL TERMID PIC'9999' INIT(1) STATIC;
/* Used to work up a unique termid */
DCL ENQ CHAR(8) INIT('AUTOPRG');
/* Used to prevent multiple access to termid */
/* If model name supplied by MTS, bypass model name selection */
IF SELECTED_MODELNAME ¬= ' '
THEN GO TO MODEL_EXIT;
/* Clear the CINIT save area and move in the VTAM CINIT RU.*/
/* This is useful if you fail to recognize the model */
/* of terminal; provide a dump and analyze this data */
SAVE_CINIT = LOW(256);
SUBSTR(SAVE_CINIT,1,CINIT_LEN) = SUBSTR(CINIT_RU,1,CINIT_LEN);
/* Now access the screen PS area in the portion of the BIND
image presented in the CINIT RU */
/* using the screen alternate height as a guide to the model
of terminal attempting logon. If this cannot be determined
then default to the first model in the table */
SELECT (AHGT); /* NOW GET SCRN ALTERNATE HEIGHT */
WHEN (12) NAME = 'M1'; /* MODEL 1 */
WHEN (32) NAME = 'M3'; /* 3 */
WHEN (43) NAME = 'M4'; /* 4 */
WHEN (27) NAME = 'M5'; /* 5 */
OTHERWISE NAME = 'M2'; /* 2 */
END;
/* Search the model entries for a matching entry. */
/* The criterion here is that a model definition should*/
/* contain the chars M2 for a model 2, and so on. */
/* For example, L3270M2, L3270M5 */
/* TERMM2, TERMM5 */
IF MODELNAME_COUNT = 0
THEN GO TO EXIT;
DO I = 1 TO MODELNAME_COUNT;
IF INDEX(MODELNAME(I),NAME)
THEN GO TO FOUND_MODEL;
END;
NO_MODEL: /* Matching entry was not found, default to first model*/
SELECTED_MODELNAME = MODELNAME(1);
GO TO MODEL_EXIT;
FOUND_MODEL: /* Move the selected model name to the return area */
SELECTED_MODELNAME = MODELNAME(I);
MODEL_EXIT: /* ENQ to stop multiple updates of counter. */
/* A simple counter is used to generate unique */
/* terminal identities, so concurrent access to */
/* this counter is denied to ensure no two get */
/* the same identifier or update the counter. */
/* To use this method the program must be defined as resident.*/
EXEC CICS ENQ RESOURCE(ENQ);
SELECTED_TERMID = TERMID; /* Set SELECTED_TERMID to
count value */
TERMID = TERMID + 1; /* Increase the count value by 1 */
IF TERMID = 9999 THEN TERMID = 1; /* Reset if too large*/
EXEC CICS DEQ RESOURCE(ENQ);
NAME_EXIT:
INSTALL_RETURN_CODE = LOW(1);
/* Set stat field to X'00' to allow
logon to be processed */
GO TO EXIT;
END INSTALL;
Before using any of the sample programs in a production environment, you would need to customize it to suit your installation.