Using the Server Activation Facility

The Server Activation Facility (SAF) is a portion of the HCI that is concerned with allocating new conversations and/or connections to existing server applications and starting new server applications when there is not already a server application that can accept another connection or conversation.

Characteristics of the Server Activation Facility:

A single server program can support any number of conversations/connections simultaneously.

A generic TP_NAME facility allows multiple servers, all with different TP_NAMES, to be known by a single generic name to LUs on the network (LU 6.2 only).

An alias TP_NAME facility allows servers with the same TP_NAME to be known by multiple alias names.

A server program can start and register itself with the HCI and, thereafter, receive all conversations bound to its TP_NAME. A server program is bound to a z/OS TCB, instead of to a z/OS ASCB, thus allowing the HCI to clean up resources held by the server when the TCB terminates, rather than having to wait for the address space to terminate.

In addition to submitting a batch job or issuing the z/OS START command, the HCI can attach a TP program within the HCI address space. This facility is designed for TP programs that need to start quickly and that can manage their own system resources without requiring any JCL allocation facilities.

Controlling the server activation facility

Parameters to the Server Activation Facility exist as members in the HCI PARMLIB data set and as entries in the configuration assembly member. Static parameters define each TP in the HCICNTPT macro or XML element as to its execution characteristics. See <HCICNTPT Element for more information.

TP_PROFILE_TABLE (TPT) — Parameters in the HCICNTPT Configuration

The TP_PROFILE_TABLE provides the following information:

• An indicator as to whether this is a generic TP_NAME
• An indicator as to whether this is an alias TP_NAME
• PARMLIB member name containing initiation instructions
• Maximum number of conversations per instance of TP_NAME
• Maximum number of instances of TP_NAME
• Maximum time job queued but not yet submitted
• Maximum time job submitted but not yet started.

Batch Jobs

From this information, the HCI can submit instances of this server, allocate as many conversations as desired to the existing instance, and can then submit another instance.
If the TP_NAME is generic, it signifies that there will be multiple instances of the server, each prestarted (as opposed to using the submit facility), and that each one of them has same TP_NAME for the length specified, and has unique values for the rest of the TP_NAME. As conversation allocation requests arrive, they will contain the same generic TP_NAME. The Server Activation Facility allocates the conversations to the existing applications limited by the two maximum values contained in the TPT.

Note that an entry in the HCI PARMLIB data set is not required for servers that do not require the generic facility capability nor need to be started automatically. The necessary control blocks are created when the application TP registers
Information needed by the HCI to actually initiate a TP is contained within the member of the PARMLIB data set named by the MEMBER= attribute of the configuration element.

The HCI submits JCL to the JES2 or JES3 internal reader in order to initiate TP programs as batch jobs. JCL within the PARMLIB member is identified by the presence of forward slashes (//) in the first two positions of the first statement in the member. The first statement is the z/OS JOB. The job name is overridden and a unique name is substituted. This unique name is constructed using the job name prefix specified in the HCICNGCA configuration element. A number is suffixed to this prefix to make this name unique and eight characters in length.

Sysplex routed tasks

Routed task support is part of the sysplex implementation and is always active when the SYSPLEX attribute has been specified through HCICNGCA. The HCI issues the z/OS ROUTE command in order to initiate server applications. To use the routed task support, the HCI PARMLIB member named in the HCICNTPT entry must contain at least a single record. The word ROUTE must be in column one, followed by either of the following:
One or more blanks, and then the name of the procedure, which must exist in the system PROCLIB
or
A list of sysplex z/OS names delimited by commas and enclosed in parentheses, followed by one or more spaces, and then the name of the procedure, which must exist in the system PROCLIB.
Other records are ignored for either of the above.

If no list is specified, the ROUTCMD= configuration parameter is checked. If ROUTCMD=NO was specified, the ROUTE is changed to a simple START. This change results in the task being started on the same z/OS on which the HCI is running. If ROUTCMD=YES was specified, all active z/OS systems are evaluated, and the one currently least routed to for HCI purposes is selected.
If HCI sysplex support is not activated, all ROUTE statements are converted to a simple START. Therefore, any route list is omitted.

ROUTE(System_List)

The route system list is evaluated as to the number of tasks that have been routed to each system. The one with the least number is chosen. The sysplex z/OS names can be
specified as a prefix name; that is, any z/OS name having the same prefix becomes part of the list. A prefix name is specified by suffixing an asterisk to the prefix.

Short notation of a single asterisk can be used to denote all z/OS systems in the sysplex. This format is used alone with no other names. In addition, you can group entries in the list by using a semicolon instead of a comma.

The groups are processed from left to right. If all z/OS systems in a group are inactive, the next group is evaluated. Again, within a group of one or more active z/OS systems, the least routed is selected. Using this grouping technique, you can establish a priority list.

You can mix prefix names and grouping in the list. If the last is a group, it is not necessary to use a semicolon prior to the ending parenthesis or comma if it is not a group.

The system list is denoted by the presence of the left and right parenthesis. This list must follow the ROUTE without spaces. Spaces within the list will be compressed out and are not used as if a comma.
If none of the z/OS systems named are active, it is treated as an error. If the sysplex has been changed to a monosystem, the ROUTE is changed to a START if the system list contained the z/OS system ID of the system that the HCI is currently running on. The HCI performs the following:

1. A unique name is constructed using the job name prefix specified in the HCICNGCA configuration macro, and to this prefix is suffixed a number to make this name unique. The unique name is used as the value for the START keyword JOBNAME=. This change is done to support those sites using Master JCL. The unique name is placed after the PROC named in the PARMLIB member.
2. Following the unique name, the HCI places the following:
   ,HCISYS=xxxx
   where xxxx is replaced with the SUBSYSTEM_ID.
3. Following this, the HCI places the following:
   ,HCIUSER=xxxxxxxx
   where xxxxxxxx is replaced with the user ID of the client that initiated the conversation request.
4. Following this, the HCI places the following:
   ,HCIGRP=xxxxxxxx
   where xxxxxxxx is replaced with the group name of the client that initiated the conversation request.
   The z/OS MCGR macro is issued with the preceding command.

The HCICNGCA macro specifies a SUBSYSTEM_ID of HCIA, and a JOBNAME prefix of HCIJOB, and ROUTCMD=YES. A PROC named SRVRPROC exists in SYS1.PROCLIB.
The HCI issues the following command:
ROUTE CW01,START SRVRPROC,JOBNAME=HCIJOB01,HCISYS=HCIA,
HCIUSER=*userid,HCIGRP=*group

The PROC has the following requirements:

• The first step in this PROC must execute a program named HCISERVR.
• This program must be passed the parameter string, which is the HCI SUBSYSTEM_ID, followed by the user ID, followed by the group name.
• Subsequent steps in the PROC invoke the user's TP program. 

Sample JCL

//IEFPROC PROC
//HCISTEP EXEC PGM=HCISERVR,PARM='&HCISYS,&HCIUSER,&HCIGRP'
//STEPLIB DD DSN=users.authorized.hci.loadlib,DISP=SHR
//USRSTEP EXEC PGM=userpgm
//USRDDS DD statements as required by userpgm

The program, HCISERVR, establishes the security environment appropriately for the execution of the user's server program. That is, the user's program executes under the user ID of the originating client user at the workstation. This environment matches the one that would exist if the user's program was submitted as a batch job instead of being started as a started task.

If HCISERVR encounters any problems, it abends and, thus, the PROC terminates. The HCI detects that the server has not registered within the allotted time and notifies the client LU that the conversation cannot be started.
HCISERVR abends with a U0100 abend and with a reason code identifying the reason for the abend.

Started tasks

The HCI issues the z/OS START command in order to initiate server applications. To use the started task support, the HCI PARMLIB member named in the HCICNTPT entry must contain at least a single record. The word START must be in column one, followed by one or more blanks, and then the name of the procedure, which must exist in one of the system PROCLIBs. Other records are ignored. The HCI performs the following:

1. A unique name is constructed using the job name prefix specified in the HCICNGCA element, and to this prefix is suffixed a number to make this name unique. The unique name is used as the value for the START keyword JOBNAME=. This is done to support those sites using Master JCL. The unique name follows the PROC named in the PARMLIB member.
2. Following the unique name, the HCI places the following:
   ,HCISYS=xxxx
   where xxxx is replaced with the SUBSYSTEM_ID.
   The z/OS MCGR macro is issued with this command.

The HCI issues the following command:

The PROC, which the user must have placed in the system PROCLIB, has the following requirements:

• The first step in this PROC must execute a program named HCISERVR.
• This program must be passed a single parameter, which is the HCI SUBSYSTEM_ID.
• Subsequent steps in the PROC execute the user's server program. 

Sample JCL

//IEFPROC PROC
//HCISTEP EXEC PGM=HCISERVR,PARM=&HCISYS
//STEPLIB DD DSN=users.authorized.hci.loadlib,DISP=SHR
//USRSTEP EXEC PGM=userpgm
//USRDDS DD statements as required by userpgm

For LU 6.2 conversations only, the program, HCISERVR, establishes the security environment appropriately for the execution of the user's server program. That is, the user's program executes under the user ID of the originating client user at the workstation. This environment matches the one that would exist if the user's program was submitted as a batch job instead of being started as a started task.

If HCISERVR encounters any problems, it abends and, thus, the PROC terminates. The HCI detects that the server has not registered within the allotted time and notifies the client LU that the conversation cannot be started.
HCISERVR abends with a U0100 abend and with a reason code identifying the reason for the abend.

Attached TPs

The HCI can attach TP programs within the HCI address space (no SYSPLEX support). These TPs are ones that required fast startup and that had no need for the allocation services of JCL. In addition, these TPs must be permitted to execute out of an authorized library.
To instruct the HCI to attach a TP, specify the term ATTACH/ATTACHX in the first position of the first statement in the PARMLIB member for the TP.

System security

This section describes the implementation of security required for the HCI Server Activation Facility. Any references to security package nomenclature are for RACF. If RACF is not the z/OS security, the z/OS site needs to make any transpositions to their security package.
The majority of z/OS installations utilize system security. The security requirements are straight forward for the Server Activation Facility process involving submitted batch servers. The workstation user must have the authorization on the z/OS system to do following:

• Execute a job with a unique job name as described in the Batch Jobs.
• Execute the module specified in any job step. In some products this could be the batch initiation of TSO using the IBM module IKJEFT01.

The started task system security concerns are more involved. The HCI requires the following three important pieces of data:

• USERID
• OWNER
• GROUP

A started task has none of these when the command is issued and they have to be assigned. This is accomplished by parameters to your site's security package (RACF, ACF/2, or TOPSECRET). Whatever USERID, OWNER, and GROUP is assigned to the started task process must have read or execute access to the HCI authorized library for the execution of the HCISERVR module in the first step of the procedure. This first step in the started task switches the USERID to that of the user, usually at a workstation, making the connection request. After this switch, the started task can access only those resources allowed by the workstation user running under the unchanged OWNER and GROUP. Therefore, the USERID used by the workstation user must have access to any z/OS system and BMC product libraries designated in those steps following the first step.

For TCP/IP connections, the appropriate USERID and, optionally, GROUP must be obtained by the server TP. The HCI is invoked to set this USERID for the TP instance.