Writing your own autoinstall program - IBM - AS/400

This section tells you how to tailor the CICS-supplied autoinstall program to extend the terminal naming facilities provided as part of the autoinstall process. You might want to do this if the device masking facility is inadequate to cope with your terminal naming conventions, or you require control over the choice of model name. You can use the source code of the supplied program and the customization example in this section as a basis. Alternatively, you can write your own program, if the supplied program does not meet your needs. You are recommended to try first a program based on that supplied with CICS/400. You must write your main program in COBOL/400, but this program may call programs in other languages. You can give any name to your customized program.

  • The source code for the CICS/400-supplied AEGTCACP program is provided in source file QCICSSAMP/QLBLSRC.
  • COBOL copybook DFHTCUDO is provided in the same source file as AEGTCACP. This copybook should be used by your autoinstall control program.
  • You can trap an abend in your customized program by making the program issue an EXEC CICS HANDLE ABEND command.
  • You must ensure that your customized program is defined as a local program in the PPT. You cannot run an autoinstall control program in a remote CICS system.
  • You should use the CRTCICSCBL command to translate and compile your autoinstall control program. You should replace the name of the supplied program AEGTCACP with that of your customized autoinstall program.

In addition to managing your autoinstall resource definition, your autoinstall control program can be customized to perform other processes. Its access to the command-level interface is that of a normal, nonterminal user task. The control program is invoked when:

  • An autoinstall install request is being processed.
  • An autoinstall delete request has just been completed.
  • An autoinstall request has previously been accepted by the user program, but the subsequent install process has failed. In this case, the control program is invoked as if for a delete request.

On each invocation of the autoinstall control program, a parameter list is passed using a communication area (COMMAREA), describing the function being performed (install or delete), and providing data relevant to the particular event.

Autoinstalling terminal definitions
The autoinstall control program is invoked when the following conditions apply:

  • An AEGTCACP PPT definition exists in the CICS system. This is the PPT definition for the autoinstall control program.
  • There is no TCT entry match for the device trying to log into the CICS system.
  • Autoinstall processing has been completed to a point where information (a terminal identifier and autoinstall model name) from the control program is required to proceed.

The COMMAREA for an install request
Input to the program is through a COMMAREA.

Figure . Autoinstall control program’s COMMAREA for install

Autoinstall control program’s COMMAREA for install

The COMMAREA, the layout of which is shown in Figure , contains the following parameters:

  • Standard Header. Byte 1 indicates the request type. This is X'F0' for an install request.
  • Pointer to NETNAME_FIELD, a variable-length field containing the network name of the terminal requesting logon, preceded by a 2-byte length field.
  • Pointer to MODELNAME_LIST, an array of names of eligible autoinstall models.The array is preceded by a 2-byte field describing the number of 4-byte name elements in the array. If there are no elements in the array, the number field is set to zero.
  • Pointer to SELECTED_PARMS, the area of storage that you use to return information to CICS/400. This area contains:

MODELNAME 4 bytes
TERMINAL_ID 4 bytes
PRINTER_ID* 4 bytes
ALTPRINTER_ID* 4 bytes
RETURN_CODE 1 byte
PRINTER_NETNAME* 10 bytes
ALTPRINTER_NAME* 10 bytes

  • Items marked with an asterisk are retained for compatibility with mainframe-based CICS, but have no function within CICS/400.
  • Pointer to DEVICE_FIELD, a field containing:

CICS/400 DEVICE_MASK 4 bytes
DEVICE_TYPE 1 byte
TERMINAL_ID 4 bytes

CICS/400 passes a list of eligible autoinstall models in the area addressed by the MODELNAME_LIST field of the COMMAREA.The control program must select a model from this list that is suitable for the device logging on, and move the model name to the first 4 bytes of the area addressed by the SELECTED_PARMS field of the COMMAREA. The supplied autoinstall control program selects the first model from this list, and CICS/400 uses this model to build the TCTTE for the device. Before returning to CICS/400, the control program must supply a CICS/400 terminal name for the device logging on, and must set the return code field to X'00' if the autoinstall request is to be allowed.

Figure . Installation parameter list

Installation parameter list

Installation parameter list

Returning information to CICS/400
At installation, the autoinstall control program is responsible for allowing or denying the connection of a new terminal resource to the CICS/400 system. This decision can be based on a number of installation-dependent factors, such as security, or the total number of connected terminals. CICS/400 takes no part in any such checking. You decide whether any such checking takes place, and how it is done.

If the install request is to proceed, the control program must do the following:

  • Return an autoinstall model name in the first 4 bytes of the area addressed by the SELECTED_PARMS field of the parameter list.
  • Supply a CICS/400 terminal name (TERMID) in the next four bytes of the return area.

The CICS/400-supplied AEGTCACP program uses the terminal identifier generated by masking as the terminal name. If you intend to use an autoinstall control program and this does not match your installations’s namingconventions, you must code your own autoinstall control program.

  • Set the return code to X'00'.

On entry to the autoinstall control program, the return code always has a nonzero value. If you do not change this, the autoinstall request is rejected.

Having completed processing, the control program must return to CICS/400 by issuing an EXEC CICS RETURN command.

Selecting the autoinstall model
CICS/400 builds the list of autoinstall models by selecting all the terminal models defined to the CICS system. The complete list of autoinstall models available to CICS/400 at any time comprises all the definitions with DEVMODEL(*MODEL) and DEVMODEL(*BOTH) that have been installed, during CICS system initialization, by the INSCICSGRP CL command, and by CEDA transaction Install group command.

CICS/400 gives all the defined models to the autoinstall control program. The CICS/400-supplied autoinstall control program merely picks the first model in the list. However, this model may not provide the attributes required in all cases. Your control program must be able to select the model that provides the characteristics you require for this terminal—for example, automatic task initiation (ATI).

If you need special models for special cases, you can use a simple mapping of, for example, the network name (generic or specific) to the autoinstall model name. Your control program could go through a table of special case network names, choosing the specified model for each. (Note that the list of models presented to the control program is in alphabetical order.) If CICS/400 does not find any models defined, or the return code in the return area addressed by the SELECTED_PARMS pointer of the parameter list is nonzero,CICS/400 issues an error message and the autoinstall installation fails. The STRCICSUSR command terminates, indicating that autoinstall processing has failed.

Setting the terminal name
The terminal name must be unique, and one through four characters long. The first character must be alphabetic, or one of the special characters $, @, or #. The remaining characters can be alphanumeric, or the special characters $, @, or #. The network name may have a maximum length of eight characters. The first character must be alphabetic, or one of the special characters $, @, or #. The remaining characters can be alphanumeric, or the special characters $, @, or #. (The terminal name is the identifier CICS/400 uses for the terminal. The network name is the identifier OS/400 uses for the terminal.)

The CICS/400-supplied autoinstall control program creates the terminal name fromthe terminal identifier generated by masking. This may not satisfy the requirement for uniqueness. One way of overcoming this problem is to use the EXEC CICS INQUIRE TERMINAL command from the control program, to determine whether the terminal name is already in use. If it is, modify the last character of the terminal identifier and check again.

However, you may be in a situation where you must continue to use unique and predictable terminal names for your terminals. Your control program must be able to assign the right terminal name to each terminal, every time the user logs on. Two possible approaches to this problem are:

  • Devise another algorithm to generate predictable TCT names from network names.

Devising an algorithm avoids the disadvantages of using a table or a file, but it might be difficult to ensure both uniqueness and predictability. If some of the information in the network name is not needed by CICS/400, it can be omitted from the terminal name. An algorithm is probably most appropriate in this situation.

  • Use a table or file to map terminal names to network names.

Using a table has two disadvantages, each of which loses you some of the benefits of autoinstall: it takes up storage and it must be maintained.

CICS/400 action on return from the control program
If the return code from the autoinstall program is zero, CICS/400 tries to acquire the device to complete the logon request. If the installation process fails, the control program is called again, as though a delete had occurred. This is necessary to allow the program to free any allocations (for example, terminal identifiers) made on the assumption that this install request would succeed.

If the return code is not zero, CICS/400 rejects the installation request in the same way as it rejects an attempt to log on from an unknown terminal when autoinstall is not enabled.

For all autoinstall activity, messages are written to the CSMT log. In addition, autoinstall activity messages are written to the job log of the process attempting the STRCICSUSR request. If an install request fails, a message is issued with a reason code. You can therefore check the output from CSMT and the job log to find out why an autoinstall request failed.

Deleting autoinstalled terminal definitions
The autoinstall control program is also called when:

  • A session with a previously automatically-installed terminal has ended.

In this case, CICS/400 issues an internal Interval Control START request for supplied transaction CATD, with the terminal identifier as the data to the request. The CATD transaction is run as a non-terminal related task in anInterval Control batch shell.

  • An autoinstall request was accepted by the user program, but the subsequent install process failed for some reason.

In this case, the autoinstall control program is called within the STRCICSUSR process where the autoinstall process has failed.Invoking the control program at deletion of autoinstalled terminal definitions enables you to reverse the processes carried out at installation. Control program at installation incremented a count of the total number of automatically installed resources, the control program at deletion could decrement that count.
The COMMAREA for a delete request
Input to the program is through a COMMAREA.
Figure . COMMAREA at deletion

COMMAREA at deletion
The COMMAREA, contains the following parameters:

  • Standard Header. Byte 1 indicates the request type. This is X'F1' for a delete request.
  • The 4-byte terminal identifier of the deleted resource. Figure 63 shows all these fields in their required order.

Figure . Autoinstall control program’s parameter list for delete

Autoinstall control program’s parameter list for delete
Note that the named resource has been deleted by the time the control program is invoked.

Naming your control program
Autoinstall processing is controlled by the program object named in the PPT definition for AEGTCACP. In the PPT definition, the PGMID must be AEGTCACP, but the PGMOBJ name may be whatever name you choose. For example:
ADDCICSTCT LIB(QTEST) GROUP(AUTO) PGMID(AEGTCACP) PGMOBJ(AUTOTEST)

Testing and debugging your control program
To help you test the operation of your autoinstall control program, you can run the program as a normal terminal-related application. Define your program and initiate it from a terminal. You can construct a dummy parameter list in your test program, upon which operations can be performed.

You can run your autoinstall control program on a terminal, and use CEDF to test and debug it, provided that the program is not being used for autoinstall processing. Because there is not a terminal associated with autoinstall processing, it is not possible to use CEDF for testing when the program is invoked as the autoinstall control program.
CEDF cannot be invoked, even if the AEGTCACP PPT entry is defined with CICSDEBUG(*DEBUG).

You can also make the test program interactive, sending and receiving data from the terminal. Your autoinstall control program should not perform any terminal related activity.

Customizing the sample program
You can customize the sample program to carry out any processing that suits your installation. Generally, your user program could:

  • Count and limit the total number of logged-on terminals.
  • Count and limit the number of automatically installed terminals.
  • Keep utilization information about specific terminals.
  • Map terminal name and network name.
  • Do general logging.
  • Handle special cases (for example, always allow specific terminals or users to log on).
  • Exercise network-wide control over autoinstall. A network-wide, global autoinstall control program can reside on one CICS/400 system. When anautoinstall request is received by a control program on a remote CICS/400 system, this global control program can be invoked and data transferred from one control program to another.

Figure . Example of how to customize the AEGTCACP sample program

Example of how to customize the AEGTCACP sample program
Example of how to customize the AEGTCACP sample program

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM - AS/400 Topics