Using the source parameter facility

The Source Parameter Facility (SPF) is new with HCI 3.0 and provides a means for supplying parameters to the HCI which does not require the two-step assembly and link edit of a configuration load module. Support for the load module remains within HCI 3.0, and the parameter macros are still shipped with the HCI. We recommend that you follow the steps described in HCI migration considerations at some time after HCI 3.0 is installed.

The Source Parameter Facility provides a much more complete diagnostic feature whereby errors in the parameter specifications can be repaired, in most cases, without contacting BMC Support for help. This DD statement defines the data set containing any error messages generated by the HCI concerning the parameter specifications.

The source parameters reside in a single XML document that contains multiple elements, each of which contains multiple attribute names and values. See Sample-XML-Parameters for an example of a parameter document.
See HCI migration considerations regarding how you can create the XML document initially. BMC has ensured that the XML created for migration matches the parameters initially specified by the set of macro attributes.

The HCIXML DD statement refers to a sequential data set or to a partitioned data set (with a member name). The sequential data set option is available only for migration purposes and we recommend that you allocate a PDS with DCB=(RECFM=FB,LRECL=80,BLKSIZE=nnnn,DSORG=PO) with primary and secondary extents and enough directory blocks so that you will not run out of them. Into this PDS you must place the XML document which contains the initial execution parameters (see The XML Document). You may name this member anything you like and specify this name on the member name associated with the DSN= operand on the HCIXML DD statement. In addition, you may place XML documents which are to be dynamically applied to the running HCI via the REFRESH XML= console command. The member name of the XML document to be used for the refresh is specified in the command, (for example: REFRESH XML=NEWCNFIG). These refresh documents are not processed unless and until you issue the REFRESH XML= command.

Dynamic Refresh Facility

Dynamic refresh is available whether you are using the two-step macro assemble/bind configuration member or the source XML facility for configuring the HCI. In either case it is possible to create a new configuration module/document and request that the HCI merge the information in the new set of parameters with those that are currently running in the HCI.
You may make changes to the original module/document and use it again for the refresh. Any unchanged parameters will remain in effect. New or changed ones will replace or add to those in effect at the time of the refresh.

We suggest that you make a copy of your running parameters, make changes to the copy, and use the copy for the refresh. In this way, any errors encountered during the refresh can be backed out by refreshing the original module/document again.
In the following section you will find every XML element and attribute which is supported in the initial and refresh module/document. If you are adding new AMB, PCB,
JCB, SIT, or TPTs, then every attribute is available to you just as it would be if you were starting the HCI from scratch. If you are updating an existing copy of one of these control blocks, then only those attributes which specify "Refresh: Yes" can be changed.

Since you may have only one HCICNGCA element, you can change only those attributes which indicate that they can be changed during a refresh.
The refresh document must be a well-formed XML document (or an assembler/bound load module with no assembly or binder errors). If this is not the case, the refresh will terminate and no changes to the running system will occur.

The XML Document

The HCI XML document is composed of one root element and at least four subordinate elements.

Root Element

The root element for the configuration document consists of <HCICNFIG> as the first statement in the data set and </HCICNFIG> as the last statement. All other configuration parameters reside within these tags:

<HCICNFIG>
... remaining parameters ...
</HCICNFIG>

Required for initial and refresh documents.

Subordinate Elements

Six distinct element names can be specified with the starting and ending root element tags:

• <HCICNGCA
• <HCICNAMB
• <HCICNPCB
• <HCICNJCB (optional)
• <HCICNSIT (optional)
• <HCICNTPT

Each of these elements are terminated by a single /> ending tag.

The following code block shows an example of a parameter document without any attributes specified.

Parameter Document Without Attributes

Relationships Between Elements

The following relationships must exist between XML elements:

• For each HCICNSIT element that specifies a TCPNAME, there must be a corresponding HCICNAMB specifying the same TCPNAME.
• For each HCICNSIT element that specifies a PORT number, there must be a corresponding HCICNPCB specifying the same PORT number.
• For each HCICNPCB element that specifies a TPNAME, there must be a corresponding HCICNTPT specifying the same TPNAME.
• For each HCICNPCB element that specifies a TPNAME, there must be a corresponding HCICNAMB specifying the same TPNAME.
• For each HCICNTPT element that specifies an ALIASOF attribute, there must be a corresponding HCICNTPT with the ALIASOF as its TPNAME.

<HCICNFIG> Element

The <HCICNFIG> element is the root element for the XML document. All XML statements reside between this element and the corresponding closing element. This element has no attributes. Therefore, unlike the subordinate elements, code it with a right angle bracket (>) immediately following the element name. This element is required for initial and refresh documents.

<HCICNGCA Element

One and only one <HCICNGCA element must be in the parameter document.

The following attribute names are valid within the HCICNGCA element. Note that each attribute is shown with its default value. The HCI migration facility will insert the actual values when it creates the initial document. You may retain these values, change them, or delete them entirely.
All attribute names are allowed in the initial configuration document, however only some of the attributes are allowed in a refresh document (see the <HCICNGCA element attribute description for more information).

<HCICNGCA Attribute List

SYSID="sysid"

Required but can be overridden by EXEC PARM.
Default: None
Refresh: No

SYSID is the short form for SUB_SYSTEM_ID and must be specified either here in the XML parameter document or on the PARM= operand of the EXEC statement that invokes the HCI. See Running-the-HCI for more information. This value must be four characters in length and is used by the HCI initialization routines to create a z/OS subsystem. You must ensure that this four-character value is unique among all subsystems running on this LPAR, and you must not define this value in SYS1.PARMLIB. The HCI dynamically creates this subsystem for you. Each HCI that you desire to run on a single LPAR must have its own unique SYSID value.
If you specify the SYSID attribute in the XML document and on the PARM= attribute of the EXEC statement, the EXEC statement PARM overrides the SYSID specified here if they differ.

ARMNAME="xxxx…xxxx"

Optional
Default: ARMNAME=""
Refresh: Yes

The Automatic Restart Management Facility in the HCI is activated by including this element and specifying a non-null name.

• 
  
  • Uppercase alphabetic characters
  • The numbers 0 through 9
  • $ # @ and underscore (_)

The first character may not be a number.
The name must be 16 characters long, padded on the right with blanks. The name must be unique across the sysplex.
Element names that begin with A through I and SYS are reserved for use by IBM.

ARMTYPE="xxxxxxxx"

Optional
Default: ARMTYPE="" 
Refresh: Yes

If ARMNAME is specified and if your installation requires that an element type be specified in the IXCARM TYPE=REGISTER macro, then specify the type here:

• 
  
  • Uppercase alphabetic characters
  • The numbers 0 through 9
  • $ # @ and underscore (_)

The first character may not be a number.
The name must be 8 characters long, padded on the right with blanks. The name does not have to be unique.
Element types that start with A through I and SYS are reserved for use by IBM.

DAE="NO|yes"

Optional.
Default: DAE="NO"
Refresh: Yes

"NO"

The z/OS Dump Analysis and Elimination (DAE) facility can be detrimental in obtaining dumps of the HCI. Specifying DAE="NO" or allowing this attribute to default to "NO" causes the HCI to change portions of the summary dump in such a way that DAE never suppresses an HCI dump.

"YES"

Specifying DAE="YES" means that the DAE facility is to suppress what it considers duplicate dumps.

DFLTUSR="userid"

Optional.
Default: DFLTUSR="HCIUSER"
Refresh: Yes

Specifies the name of a valid RACF (ACF/2 or TOPSECRET) user ID to be used by the HCI when TP jobs are submitted or started and when there is no other user ID available.
This user ID must be assigned within the security system and must be granted authority to perform whatever processing the TP requires up to the point in time
when the TP issues one of the set security calls. Until that time, the new user ID is in effect.

DMPCLAS="class"

Optional.
Default: None
Refresh: Yes
Specifies a valid JES/n output class to which SNAP dumps are to be directed. If this attribute is omitted, then the DMPPFX, DMPUNIT and DMPVOL attributes define the output data set to contain SNAP dump information.

DMPPFX="SDUMP|prefix"

Optional.
Default: DMPPFX="SDUMP"
Refresh: Yes

"SDUMP"

Specifies that all dumps taken by the HCI are system dumps (via SDUMPX) and are directed to the SYS1.DUMPxx (or customer-defined) data set. The DMPUNIT, DMPVOL, and DMPCLASS attributes are ignored.

"prefix"

Causes a data set to be allocated whose DSNAME is prefixed by this prefix and a SNAP dump is taken to this data set. In this case, the DMPUNIT and DMPVOL attributes further define the location of the data set. The prefix can be from 1 to 12 valid characters for a DSNAME prefix.

DMPUNIT="unitname"

Optional.
Default: None
Refresh: Yes

Specifies the unitname for SNAP dumps allocated by the HCI. If this attribute is omitted, then the DMPPFX attribute must specify "SDUMP". Unitname must be a valid name for DASD allocation at your installation; for example,
DMPUNIT="SYSDA".

DMPVOL="volser"

Optional.
Default: None
Refresh: Yes

Specifies the VOLSER for SNAP dumps allocated by the HCI. If this attribute is omitted, then the DMPPFX attribute must specify "SDUMP". VOLSER must be a valid volume serial number for DASD allocation at your installation.

EOM="YES|no"

Optional.
Default: EOM="YES" 
Refresh: Yes

Specifies whether the HCI subsystem is to monitor the system for end of memory (EOM) events.
"YES"

End of task events, which are always monitored, will provide the necessary protection against TP program ending without the HCI being aware of the termination. The default exists due to downward compatibility requirements.

"NO"

Causes less CPU overhead by the HCI.

INTERNAL="YES|no"

Optional.
Default: INTERNAL="YES"
Refresh: Yes

Specifies whether the HCI is to support TPs attached as subtasks within the HCI address space. We recommend specifying YES or accepting the default for all current implementations of the HCI.

JESCHAR="$".

Optional.
Default: JESCHAR="$" (U.S. dollar sign)
Refresh: Yes

Specifies the command character used from the master console or from an SDSF log screen to issue commands to the JES2 or JES3 subsystem. The value of this attribute is used by the HCI as the first character of the command used to cancel TP programs that have been started by the Server Activation Facility, but which have not registered with the HCI within the allowable time limit.

In this way, multiple JES subsystems can support HCI TP programs.

JESID="2|3"

Optional.
Default: JESID="2" 
Refresh: No

Specifies that either JES2 or JES3 is the primary subsystem for the LPAR on which the HCI is executing. Various functions within the HCI depend on the correct setting of this attribute.

JESJPRM="NO|yes"

Optional.
Default: JESJPRM="NO" 
Refresh: Yes

Specifies whether the HCI should add a /JOBPARM SYSAFF= for JES2 systems or a //MAIN SYSTEM=xxxxxxxx for JES3 systems to JCL submitted by the HCI to start TP programs. If your JCL for TP programs is to run on systems other than the one on which the HCI is executing, then omit this attribute or specify JESJPRM="NO".

JRNMASK="0000000000000000|FFFFFFFFFFFFFFFFFF"

Optional.
Default: JRNMASK="0000000000000000"
Refresh: Yes

Specifies exactly 16 hexadecimal digits (0-9 and A-F) that are used to control which journal events are to be collected when journaling is active.

"0000000000000000"

Causes no journal events to be written to the HCI journal.

"FFFFFFFFFFFFFFFFFF"

Causes all journal events to be written to the HCI journal.

MAININT="nnnnnn"

Optional.
Default: MAININT="1500"
Refresh: Yes

Specifies the interval for the main timer in the HCI. This number is specified in hundredths of a second. Valid values are 1 through 360000. The default (15 seconds) is suitable for all installations. If this value is increased appreciably, the time between the termination of a TCP/IP connection or the termination of a TP program and when the HCI processes this event may be increased.

MAXCCBS=""nnnnn"

Optional.
Default: MAXCCBS="1024"
Refresh: Yes

Specifies the maximum number of concurrent conversations or connections that the HCI will support. Setting this attribute to a large number increases private storage usage, but otherwise does not cause any negative effects. Valid values are 128 through 32768. Each CCB is 1376 (decimal) bytes long.

MAXDCBS="nnnnn"

Optional.
Default: MAXDCBS="32" 
Refresh: Yes

Specifies the maximum number of concurrent discrete destinations that the HCI will support. Setting this attribute to a large number increases private storage usage, but otherwise does not cause any negative effects. Valid values are 8 through 32768. Each DCB is 760 (decimal) bytes long.

MAXJRES="nnnnn"

Optional.
Default: MAXJRES="8192"
Refresh: Yes

Specifies the maximum number of concurrent journal requests that the HCI will support. Setting this attribute to a large number increases private storage usage, but otherwise does not cause any negative effects. In addition, a large number ensures that no journal records are lost due to JRE exhaustion. Valid values are 512 through 32768. Each DCB is 16 (decimal) bytes long.

MAXLUBS="nnnnn"

Optional.
Default: MAXLUBS="16" 
Refresh: Yes

Specifies the maximum number of SNA LU2 sessions that the HCI will support. If you are not supporting any LU2 remote partners, then allowing this attribute to use the default is sufficient. Valid values are 1 through 2768. Each LUB is 496 (decimal) bytes long.

MAXRCBS="nnnnn"

Optional.
Default: MAXRCBS="32" 
Refresh: Yes

Specifies the maximum number of concurrent TP program address spaces that the HCI will support. Each address space can be associated with multiple TP users, but in most cases it is a one-for-one correspondence. Region control blocks (RCBs) are allocated from ECSA (SP=241), and therefore this number should not be excessively bigger than necessary. Valid values are 8 through 32768. Each RCB is 96 (decimal) bytes long.

MAXUIBS="nnnnn"

Optional.
Default: MAXUIBS="32"
Refresh: Yes

Specifies the maximum number of concurrent TP program TPNAMES that the HCI will support. User interface blocks (UIBs) are allocated from ECSA (SP=241), and therefore this number should not be excessively bigger than necessary. Valid values are 8 through 32768. Each UIB is 1040 (decimal) bytes long.

MAXWRES="nnnnn"

Optional.
Default: MAXWRES="4096"
Refresh: Yes

Specifies the maximum number of concurrent work requests that the HCI will support. Work request elements (WREs) are allocated from ECSA (SP=241), and therefore this number should not be excessively bigger than you find necessary. Valid values are 8 through 32768. Each WRE is 1040 (decimal) bytes long.

OACBINT="nnnnn"

Optional.
Default: OACBINT="3000"
Refresh: Yes

Specifies the time in hundredths of a second that the HCI will allow to elapse between attempts to open a VTAM ACB specified by the ACBNAME attribute of an HCICNAMB element. Valid values are 1 through 360000.

OPCMD="WTOR|modify"

Optional.
Default: OPCMD="WTOR" 
Refresh: Yes

Specifies how operator commands are entered to the HCI.

"WTOR"
Specifies that a Reply to Operator command (r nn,) is to be used.

"MODIFY"
Specifies that the z/OS MODIFY (F) command is to be used.

PACING="nnnnn"

Obsolete.
Default: PACING="0" 
Refresh: N/A

No longer used by the HCI. If the attribute is specified, the value must be 0.

PREPROC="xxxxxxxx"

Optional.
Default: PREPROC="HCIYPREP"
Refresh: Yes

Specifies the name of a procedure in SYS1.PROCLIB (or an appropriate user procedure library) that starts the initialization of the secondary HCI on each member of a parallel sysplex. The main HCI is initialized by the customer via JCL or a started task. The HCI automatically routes z/OS START commands to each other member of the sysplex indicating that the PROC named in the PREPROC attribute be started. Name this PROC any maximum eight-character name, but the PROC must be available to every member of the sysplex. See Using-the-Server-Activation-Facility for more information about this initialization procedure.
If the SYSPLEX attribute is omitted (indicating no sysplex support requested), then the PREPROC attribute is ignored.

ROUTCMD="NO|yes"

Optional.
Default: ROUTCMD="NO" 
Refresh: Yes

Specifies whether TP programs that are initiated by START commands are to be routed to the member of the sysplex indicated on the member in the HCI //PARMLIB DD.
"NO"

Specifies that the z/OS START command is to be issued only on the system on which the primary HCI is running.

"YES"

Specifies to route z/OS START commands to each z/OS in the SYSPLEX.

SECFAC="xxxx...xxxx"

Optional.
Default: None
Refresh: Yes

Specifies the name of a Facility Class entity that is to be checked when a TP program issues a CWOPER call in order to issue an operator command. The user ID under which the TP is executing must have ACCESS(UPDATE) to the Facility Class entity in order to issue the CWOPER call to issue the REFRESH command. No other operator commands may be issued from this call and none is protected by the RACF entity.

SRVRJOB="xxxxx"

Optional.
Default: SRVRJOB="HCITP"
Refresh: Yes

Specifies a one- to five-character job name prefix that the HCI uses for all TP programs submitted by the HCI. A one- to three-digit numeric suffix is added onto this prefix and incremented each time the job is submitted in order that the job names will be unique. When the suffix reaches 9, 99, or 999 (depending upon the length of the prefix), the number wraps to 0, 00, or 000. Specifying a single space has the same effect as specifying a SRVRJOB with a null input on the HCICNGCA macro.

SYSPLEX="xxxx"

Optional.
Default: None
Refresh: No

Specifies a four-character subsystem ID to be assigned to each of the sysplex HCI members. The value must be exactly four characters in length and must consist of uppercase letters and numbers only.
Omitting this attribute specifies that you do not want sysplex support to be activated.

TCPAMSG="NO|yes"

Optional for TCPACCESS only.
Default: TCPAMSG="NO" 
Refresh: Yes

Specifies whether the TCPACCESS TERROR macro is to be used to display error messages if your TCP/IP protocol stack is CA's TCPACCESS product.
"NO"

Sends TCPACCESS messages to the //HCIPRINT DD.

"YES"

Use the TCPACCESS TERROR macro to display error messages.

TPSEC="NO|yes"

Optional.
Default: TPSEC="NO" 
Refresh: Yes

Specifies whether you want the HCI to ensure that the user ID under which a TP program is executing has access to the TPNAME that it is connecting to.
"NO"

Specifies that no RACF checking of the user ID versus the TPNAME is to occur.

"YES"

Specifies that the user ID must have ACCESS(READ) to the FACILITY CLASS entity in order for the HCI to allow execution of the TP. The FACILITY CLASS entity name is constructed by prefixing the TPNAME with the four-character subsystem ID of the HCI.

/>

Close HCICNGCA element. You must include a forward slash and right angle bracket (/>) XML construct to close the <HCICNGCA element. Failure to do so causes the document to not be well-formed and parsing to fail.

<HCICNAMB Element

Include at least one <HCICNAMB element in the XML document, but any number can be specified. Each one specifies an ACB name for LU6.2 and LU2 communication to be opened and used for inbound and outbound connections. For TCP/IP, the <HCICNAMB element specifies the name of a TCP/IP region active on this LPAR. The LUTYPE= attribute specifies what kind of connection (VTAM or TCP/IP) is to be created by this HCICNAMB element.
For the refresh capability, existing AMB's can be updated via an HCICNAMB element in the refresh document and new AMB's can be added. The ACBNAME or TCPNAME is used to associate an AMB element in the refresh document with ones already defined by the initial document. For existing AMB's only the TCPPSWD can be changed dynamically. New AMB's can contain any of the defined attributes.

The <HCICNAMB element attributes are described as follows:

LUTYPE="lutype"

Required.
Default: None
Refresh: No

Specifies one of the following valid types indicating the access method and protocol to be used for all connections/conversation defined by this HCICNAMB element:

• 
  
  • TCPIP
  • LU62
  • LU2
  • TCPACCESS.

RCVLN="nnnnnnnn"

Required.
Default: None
Refresh: No

Specifies the maximum data length in bytes that can be received on the connection/conversation described by the current HCICNAMB element. Valid values are 4096 through 16777211.

TCPNAME="xxxxxxxx"

Optional.
Default: [Default TCP/IP region name]
Refresh: No

Specifies the name of a TCP/IP region that is to process connections to/from this HCICNAMB element. If you have multiple active TCP/IP regions and you want a particular one to be chosen, then specify the region name here. From any ISPF command line, you can issue the TSO NETSTAT HOME command to find the name of your TCP/IP region.

ACBNAME="xxxxxxxx"

Required if LUTYPE is LU62 or LU2.
Default: None
Refresh: No

Specifies the VTAM ACBNAME attribute that is to be used by conversations associated with this HCICNAMB.

GENNAME="xxxxxxxx"

Optional.
Default: None
Refresh: No

Specifies the VTAM generic name to be used by conversations associated with this HCICNAMB. The generic name is moved into the node initialization block (NIB) prior to use. If this name is present, the HCI indicates to VTAM that it is to be known by this generic name, and a SETLOGON is issued to add the generic name. Multiple HCICNAMB elements may specify the same generic name, and multiple HCIs on the sysplex may also specify the same name.

HPNS="CURR"

Optional.
Default: HPNS="CURR" 
Refresh: No

Specifies the only valid value for the HPNS macro attribute for HCI Release 3.0. In prior HCI releases, the HPNS attribute caused a particular TCP/IP interface to be used.

IPV6="NO|yes"

Optional.
Default: IPV6="NO" 
Refresh: No

Specifies whether the HCI should attempt to use the TCP/IP IPv6 interface for connections to/from remote hosts and this HCI. See IPv6 support for a more complete description.
If your TCP/IP region on this LPAR does not support IPv6, then specify IPV6="NO"; otherwise, an error message is generated when an attempt is made to obtain an IPv6 socket. If the IPv6 SOCKET obtain fails, the HCI reverts to an IPv4 socket and communication proceeds as usual. However, if the TCP/IP region on this LPAR does support IPv6, specify IPV6="YES" in order to take advantage of this support.

MODEL="n"

Optional.
Default: None
Refresh: No

Applies only to HCICNAMB elements specifying LUTYPE=LU2. This attribute specifies whether the 3270 model supported by the HCI is a model 2, 3, 4, or 5. Specifying the correct model ensures that an appropriate BIND image can be sent to the remote partner LU. Omit this attribute if the partner LU2 model is not known.

PGMNAME="xxxxxxxx"

Optional and ignored by HCI Release 3.0.
Default: Program name appropriate for the LUTYPE specified.

Specifies the main program name to be invoked for the LUTYPE specified on the HCICNAMB element. Omit this attribute and allow the HCI to supply the correct name. You may see this name in the XML generated by the HCI and which is written to the //HCIPRINT DD. You may leave this attribute in the XML or delete it.

TCPPSWD="xxxxxxxx"

Optional.
Default: None
Refresh: Yes
Applies an optional password to TCPACCESS connections. Omit this attribute for any but TCPACCESS HCICNAMB elements. Supply it only if a password has been specified in the TCPACCESS definition data sets.

/>

Close HCICNAMB element. You must include a forward slash and right angle bracket (/>) XML construct to close the <HCICNAMB element. Failure to do so causes the document to not be well-formed and parsing to fail.

<HCICNPCB Element

At least one <HCICNPCB element must be present in the XML document if you are defining any TCP/IP connections. Any number can be specified.
For the refresh capability, existing PCBs can be updated or new ones can be added. Port number is used to define an existing PCB. When a new PCB is added all the attributes below can be specified. The Refresh specification applies to updating existing PCBs only.

The <HCICNPCB element attributes are described as follows:

PORT="nnnnn"

Required.
Default: None.
Refresh: No

Specifies the port number associated with the connection described by this HCICNPCB element. Valid port numbers are from 1 through 65535. Check with your network administrator to ensure that you have not accidentally specified a port number already in use.

The port number is used as follows:

• 
  
  • For "TYPE=LOCAL" (inbound connections), the PORT number specifies the port on which the HCI listens for incoming connection requests.
  • For "TYPE=REMOTE" (outbound connections), the PORT number specifies the port on the remote host to which connections are to be made.
  • For "TYPE=BOTH" (both inbound and outbound), the PORT number specifies both the inbound listen port and the outbound connection port.

TCPNAME="xxxxxxxx"

Optional.
Default: [Default TCP/IP region name]
Refresh: No.

Specifies the name of a TCP/IP region that is to process connections to/from this HCICNPCB element. If you have multiple active TCP/IP regions and you want a particular one to be chosen, then specify the region name here. This name must match a TCPNAME attribute in an <HCICNAMB element.

TPNAME="xxxx...xxxx"

Required.
Default: None
Refresh: Yes

Specifies the TP program name that is also specified in an HCICNTPT element associated with connections defined by this HCICNPCB element. Valid TP program names are 1 through 64 characters in length.

DATAENC="ASCII|EBCDIC"

Optional.
Default: DATAENC="ASCII"
Refresh: No

Specifies the data encoding used by TP programs for connections defined by this HCICNPCB element. This attribute is not used by HCI Release 3.0, but if specified must be one of the values shown.

DVIPA="IPv4|IPv6 address"

Optional.
Default: None
Refresh: Yes

Specifies the address (IPv4 or IPv6) from which connections are accepted for this HCICNPCB element if TCP/IP VIPARANGE processing has been defined in the TCP/IP configuration data sets. This address overrides the IP address of the host on which the HCI is running, thus allowing you to move the HCI from one LPAR to another retaining the IP address known to the network clients.
The address must be in presentation form for one of the following:

• 
  
  • IPv4 addresses: nnn.nnn.nnn.nnn, where nnn is a decimal number from 0 through 255 for each of the four sub-elements.
  • IPv6address: hhhh:hhhh::hhhh where hhhh is a hexadecimal number (0-9, A-F) for each of the one to eight sub-elements.

DVIPN="IP name"

Optional.
Default: None
Refresh: Yes

Specifies the 1- to 64-character name, known to your HOSTS file or to your DNS server, from which connections are accepted for this HCICNPCB element If TCP/IP VIPARANGE processing has been defined in the TCP/IP configuration data sets. This name overrides the IP name of the host on which the HCI is running thus allowing you to move the HCI from one LPAR to another retaining the IP name known to the network clients.

RECFM="F|U|V"

Required.
Default: None
Refresh: Yes

Specifies the format of records received and sent by the HCI for connections defined by this HCICNPCB element. The valid values are:

• 
  
  • "F": Fixed length. Length specified by the LRECL attribute
  • "U": Undefined length. Length specified by the EORCHRS and EOBCHRS attributes
  • "V": Variable length. Length specified by the LLZZ attribute

EORCHRS="hhhh…hhhh"

Optional.
Default: None
Refresh: Yes

Specifies the hexadecimal characters that define the end of a record if RECFM="U" for this HCICNPCB element. When the HCI recognizes this set of characters, it considers the record complete and passes it to the TP program in response to a READ call. Valid values are 2 through 16 hexadecimal characters.
If there is a differentiation between End-of-Record and End-of-Block, then also specify the EOBCHRS attribute.

EOBCHRS="hhhh…hhhh"

Optional.
Default: None
Refresh: Yes

Specifies the hexadecimal characters that define the end of a block of data if RECFM="U" for this HCICNPCB. When the HCI recognizes this set of characters, it considers the block of input data complete and passes it to the TP program in response to a READ call. Valid values are 2 through 16 hexadecimal characters.

LRECL="nnnnn"

Optional.
Default: LRECL="4096" 
Refresh: Yes

Specifies the size of each logical record to be passed to the TP program if RECFM="F" for this HCICNPCB. Valid values are 16 through 32768 bytes.

LLZZ="(s1,s2,s3,s4,s5,s6)"

Optional.
Default: None
Refresh: Yes

Specifies the location, length, type, and disposition of the length field that exists on each block of data if RECFM="V" for this HCICNPCB. The six subfields must all be present in the following order:

1. Starting location in the record where the length field begins. Valid values are 000 through 32768.
2. Length of the length field. Valid values are 1 through 4.
3. Encoding of the length field: CHARA (ASCII character), CHARE (EBCDIC character), BINB (binary big endian), or BINL (binary little endian).
4. INCL if the length includes itself, or EXCL if the length does not include itself. Note that INCL is the way variable length records on DASD are defined.
5. MAKE if the HCI is to provide the length field on output, or USE if the length field already exists in the output message.
6. DELETE if the HCI is to remove the length field from inbound data, or KEEP if the length field is to be passed to the TP program on input messages.

PROTOCOL="UNIFACE|UNIFACE8|GCS"

Optional.
Default: None
Refresh: Yes

Specifies one of the three BMC product protocols. If connections defined by this HCICNPCB element are to be processed by one of the BMC product protocols, then omit the other following formatting attributes, whose values will automatically be set by the HCI:

• 
  
  • DATAENC
  • LLZZ
  • RECFM
  • LRECL.

TYPE="LOCAL|REMOTE|BOTH"

Optional.
Default: TYPE="LOCAL"
Refresh: No.

Specifies whether this HCICNPCB element represents a listening port (TYPE="LOCAL") or a connecting port (TYPE="REMOTE") or both listening and connecting. Further, TYPE="LOCAL" implies that the port number in this HCICNPCB is a port on this host. TYPE="REMOTE" implies that the port number in this HCICNPCB is a port on the remote host.

/>

Close HCICNPCB element. You must include a forward slash and right angle bracket (/>) XML construct to close the <HCICNPCB element. Failure to do so causes the document to not be well-formed and parsing to fail.

<HCICNJCB Element

One <HCICNJCB element for each journal data set you have defined, initialized, and intend to use must be present in the XML document. See Using-the-journaling-facility for more information about the HCI's journaling facility. We recommend that you define three journal data sets of sufficient size each to hold ten minutes of activity.

Even though you have specified these data sets in <HCICNJCB elements, nothing is written to them (and no overhead is encountered) if the journal mask attribute (JRNMASK=) in the <HCICNGCA element is set to all zeros. You can change this setting dynamically by operator commands if you want to start and stop journal activity. However, if no journals are defined, you cannot dynamically start capturing journal records.

The <HCICNJCB element attributes are described as follows:

DDNAME="xxxxxxxx"

Required.
Default: None
Refresh: Yes

Assigns a one- to eight-character DD name to the journal whose data set name is specified by the DSNAME attribute.

DSNAME="xxxxx…xxxxx"

Required.
Default: None
Refresh: Yes

Assigns a 1- to 35-character data set name to the journal whose DDNAME is specified by the DDNAME attribute. The name must have been initialized as documented in Using-the-journaling-facility.

/>

Close <HCICNJCB element. You must include a forward slash and right angle bracket (/>) XML construct to close the <HCICNJCB element. Failure to do so causes the document to not be well-formed and parsing to fail.

<HCICNSIT Element

One <HCICNSIT element for each outbound connection that a TP program wants to make must be present in the XML document. Although originally designed for LU 6.2 conversations, the side information table (SIT) concept and implementation are applicable to TCP/IP as well. Each <HCICNSIT element defines the parameters for an outgoing connection/conversation in such a way that the TP program itself need not be aware of many of these values.

The refresh facility can update existing SIT elements and can add new ones. The SYMNAME attribute is used to define an existing or new SIT. For new SITs all attributes can be specified in the refresh document. For existing SITs, the Refresh specification on each attribute below defines whether it can be changed or not.

The <HCICNSIT element attributes are described as follows:

SYMNAME="xxxxxxxx"

Required.
Default: None
Refresh: No

Assigns a symbolic destination name for TP programs to specify for connections defined by this HCICNSIT element. This symbolic name must be known to the TP program. Therefore, you must coordinate assigning a name with the development group. BMC products that use the HCI will define the names you are to use. See the individual BMC product's installation guide for requirements for the HCICNSIT elements.

The valid value for this attribute is a one- to eight-character name known to the TP program for its outbound connection/conversation requests.

LUTYPE="lutype"

Required.
Default: None
Refresh: No.

Specifies one of the following valid lutypes indicating the access method and protocol to be used for all connections/conversation defined by this <HCICNSIT element:

• 
  
  • TCPIP
  • LU62
  • TCPACCESS.

BYPDLAY="NO|yes"

Optional for TCP/IP only.
Default: BYPDLAY="NO" 
Refresh: Yes

Specifies whether upon TCP/IP close the system-defined delay interval is to be invoked in order to ensure that all TCP/IP traffic has exited the network and has been processed by the remote host.

"NO"

Specifies that this delay is to be used, which causes a noticeable performance implication of waiting for this period of time.

"YES"

Specifies that the no-delay period is to be waited and that the connection is to be closed immediately.

IPADDR="nnn.nnn.nnn.nnn"|"hhhh:...hhhh"

Optional for TCP/IP only.
Default: None
Refresh: Yes

Specifies the IPv4 or IPv6 address of the remote host with which connections defined by this HCICNSIT entry are to be made. If you specify this attribute, then omit the IPNAME attribute. The maximum length of the IP address value is 15 bytes for IPv4; and, 39 bytes for IPv6. The valid presentation form of the IPv4 address is dotted decimal (10.10.10.10). The valid form for IPv6 is colon hexadecimal (0101:01FF:AAFF:CE01::)

IPNAME="xxxxx…xxxxx" 

Optional for TCP/IP only.
Default: None
Refresh: Yes

Specifies the name, known to your DNS or the local HOSTS data set, of the remote host with which connections defined by this HCICNSIT entry are to be made. If you specify this attribute, then omit the IPADDR attribute. The maximum length of this IPNAME value is 64 bytes. If the name is longer than this maximum, then you must use IPADDR instead.

h7.PORT="nnnnn"

Required for TCP/IP only.
Default: None
Refresh: Yes

Specifies the port number upon which the remote partner host is listening and to which connections defined by this HCICNSIT element are to be made. Valid port numbers are from 1 through 65535.

TCPNAME="xxxxxxxx" 

Optional for TCP/IP only. 
Default: None
Refresh: Yes

Specifies the name of a TCP/IP region running on this LPAR through which connections to the remote partner host defined by this HCICNSIT element are to be made. If you specify this attribute, then you must also specify an <HCICNAMB element with the same TCPNAME. Hence the connection to the desired protocol stack can be made. If this attribute is omitted and if TCPNAME is omitted from all <HCICNAMB elements, then the first one defined is used for these outbound connections.

LLUNAME="xxxxxxxx"

Optional for LU6.2 only.
Default: LLUNAME=[First HCICNAMB ACBNAME]
Refresh: Yes

Specifies the ACBNAME of one of the <HCICNAMB element entries in order that a particular one be used as the local LU for conversations defined by the <HCICNSIT element. If this attribute is omitted for LU 6.2 conversations, then the first LU 6.2 <HCICNAMB element is used as a default.

MAXS="0"

Optional for LU6.2 only.
Default: MAXS="0" 
Refresh: Yes

Has been removed from use and VTAM now supplies this information automatically for LU 6.2 conversations. If you specify this attribute, you must specify its value as "0".

MINCW="0"

Optional for LU6.2 only.
Default: MINCW="0" 
Refresh: Yes
Has been removed from use and VTAM now supplies this information automatically for LU 6.2 conversations. If you specify this attribute, you must specify its value as "0".

MINCL="0"

Optional for LU6.2 only.
Default: MINCL="0" 
Refresh: Yes

Has been removed from use and VTAM now supplies this information automatically for LU 6.2 conversations. If you specify this attribute, you must specify its value as "0".

MODNAME="xxxxxxxx" 

Optional for LU6.2 only.
Default: None
Refresh: Yes

Specifies the Logon Mode Table entry name to be used for the parameters for the outbound conversation defined by this <HCICNSIT element.

PARSESS="YES|NO"

Optional for LU6.2 only.
Default: PARSESS="YES"
Refresh: Yes

"YES"

Specifies that the LU associated with this outbound conversation supports parallel sessions and these should be initiated when the session is established.

"NO"

Specifies that the LU associated with this outbound conversation does not supports parallel sessions.

PASSWD="******" 

Optional for LU6.2 only.
Default: None
Refresh: Yes

Assigns a one- to eight-character password for the user ID specified in this HCICNSIT element. The user ID/password combination is sent to the partner LU in the FMH-5 and is used by the partner to ensure that the initiator of the conversation is valid. If the PASSWD attribute is specified, the USERID attribute must be specified as well.

PLUNAME="xxxx…xxxx" 

Optional for LU6.2 only.
Default: None
Refresh: Yes

Specifies the 1- to 17-character partner LU name for the remote end of the conversations established by this HCICNSIT entry. Specify the value as NETID.LUNAME, for a maximum of 17 bytes in length. This value can be supplied by the local TP program before allocating a conversation with the remote partner.

TPNAME="xxxxx...xxxx" 

Optional for LU6.2 only.
Default: None
Refresh: No.

Specifies the 1- to 64-character name of the TP program running in the partner LU as defined by PLUNAME attribute.

USERID="********"

Optional for LU6.2 only.
Default: None
Refresh: Yes

Assigns a 1 - 8 character user ID that is sent to the partner LU in the FMH-5 and is used by the partner to ensure that the initiator of the conversation is valid.

/>

Close <HCICNSIT element. You must include a forward slash and right angle bracket (/>) XML construct to close the <HCICNSIT element. Failure to do so causes the document to not be well-formed and parsing to fail.

<HCICNTPT Element

One <HCICNTPT element for each inbound connection that a TP program wants to make must be present in the XML document. Although originally designed for LU 6.2 conversations, the teleprocessing program table (TPT) concept and implementation are applicable to TCP/IP as well. Each <HCICNTPT element defines the parameters for an inbound connection/conversation in such a way that the TP program itself need not be aware of many of these values.
The <HCICNTPT element attributes are described as follows:

TPNAME="xxxx...xxxx"

Required for LU6.2 and TCP/IP.
Default: None
Refresh: Yes

Specifies the name by which the TP program is known. The program itself must know this name from its own sources, and the TP identifies itself to the HCI in the CWRNU call by this name. Valid TP program names are 1 through 64 characters in length.
A required <HCICNPCB element in this XML document must specify the same TPNAME attribute value as is specified here. These two names must match exactly in case and length.

ALIASOF="xxxx…xxxx"

Optional for LU6.2 and TCP/IP.
Default: None
Refresh: Yes

Specifies a TP program name that acts as the primary name for this alias. The ALIASOF attribute value must specify a TPNAME that is defined in its own <HCICNTPT element within this XML document. A TP program can register with the HCI as either the TPNAME specified in this element or the TPNAME specified in the ALIASOF attribute.

MEMBER="xxxxxxxx"

Optional for LU6.2 and TCP/IP.
Default: None
Refresh: Yes

Specifies the name of a member in the partitioned data set (PDS) defined in the HCI execution JCL with DDNAME //HCIPARM DD. This member contains instructions to the HCI as to how the TP program defined by this HCICNTPT element is to be started. That is, the member contains JCL, a START command, an ATTACH command, or a ROUTE command. See Using-the-Server-Activation-Facility for a more information of this subject.

MAXCNV="nnnnn"

Optional for LU6.2 and TCP/IP.
Default: MAXCNV="1" 
Refresh: Yes

Specifies the maximum number of conversations that one instance of the TP program can handle and applies only to TP programs capable of managing multiple conversations or connections simultaneously. The minimum number is 1, and the maximum number is not defined. When one instance of this TP program reaches its maximum, the next inbound connection or conversation request causes a new instance of the TP program to be started. New conversations/connections are passed to an existing instance of this TP program in a round robin manner until all instances currently executing are at this maximum value.
If you specify a value greater than 1, also specify the MULTSEC="YES" attribute.

For single-threaded TP programs that cannot handle multiple conversations, specify MAXCONV="1" or allow this attribute to default. Hence, each conversation or connection request results in a new instance of the TP program being started.

MAXTPS="nnnnn"

Optional for LU6.2 and TCP/IP.
Default: MAXTPS="999" 
Refresh: Yes

Specifies the maximum number of instances of this TP program which will be initiated by the HCI and applies to all TP programs whether managing multiple conversations. When this maximum is reached, subsequent conversation or connection requests are denied. The minimum number is 1, and the maximum number is not defined.

MULTSEC="NO|yes"

Optional for LU6.2 and TCP/IP.
Default: MULTSEC="NO" 
Refresh: Yes

Specifies whether the TP program defined by this HCICNTPT element is capable of handling multiple simultaneous conversations or connections.

"NO"

Specifies that only one conversation or connection can be processed at one time by this TP program.

"YES"

Specifies that this TP program can handle multiple simultaneous conversations or connections. If this attribute is set to MULTSEC="YES", specify a value greater than 1 for the MAXCNV attribute to indicate how many conversations or connections the TP program can handle at one time.

MAXPTIM="nnnnn"

Optional for LU6.2 and TCP/IP.
Default: MAXPTIM="1440"
Refresh: Yes

Specifies the number of seconds that the HCI will wait after a TP program starts before a conversation or connection request arrives from a remote host or LU. If this time is exceeded, the connection or conversation request is denied and the TP program is canceled. Valid values are 0 through 32768 seconds.

MAXSTIM="nnnnn"

Optional for LU6.2 and TCP/IP.
Default: MAXSTIM="1440"
Refresh: Yes

Specifies the number of seconds that the HCI will wait after submitting or starting a TP program before that program issues a Register New User call indicating that it is ready to handle the inbound connection or conversation request. If this time is exceeded, the connection or conversation request is denied and the TP program is canceled. Valid values are 0 through 32768 seconds.

RECVLEN="nnnnn"

Optional for LU6.2 and TCP/IP.
Default: RECVLEN="4096"
Refresh: Yes

Specifies the maximum length in bytes of any message to or from the remote host or TP connected to the TP program defined by this HCICNTPT element. Valid values are 4096 through 16777211.

SRVRJOB="xxxxxxxx"

Optional for LU6.2 and TCP/IP.
Default: None
Refresh: Yes

Specifies a job name prefix to be used for TP programs submitted by the HCI defined by this HCICNTPT element. This attribute overrides the SRVRJOB attribute for this TP
program only. If this attribute is omitted, then the SRVRJOB attribute is used as the job name prefix.

USERSEC="YES|no"

Optional for LU6.2 and TCP/IP.
Default: USERSEC="YES"
Refresh: Yes

Specifies whether RACF (ACF/2 or TOPSECRET) RACROUTE calls are to be made to ensure that the user ID under which a TP program is executing has the authority to assign itself as the TP name specified in this HCICNTPT element and in the associated register new user call.

"YES"

Specifies that the facility class entity named the same as the TP name is to be checked and the user ID under which this TP program is executing must have at least ACCESS(READ) to this entity. If it does not have this access, then the register new user call fails. If USERSEC="YES" is specified, but no facility class entity named by the TPNAME exists, then access is allowed.

"NO"

Specifies that RACF (ACF/2 or TOPSECRET) RACROUTE calls are not to be made.

DSNAME="xxxx.xxxx"

Ignored for all connection types.
Default: None.
Refresh: N/A

The DSNAME attribute has been removed from the HCI and is no longer processed. The MEMBER attribute can only specify the name of a member in the //HCIPARM DD data set, and no optional data set is supported.

CATEGORY="xxxx…xxxx" 

Optional for LU6.2 and TCP/IP.
Default: None
Refresh: Yes

Specifies a 1- to 16-byte name used by the TP program to associate different HCICNTPT elements with a particular name from a set of them. This attribute is not used by the HCI, but is passed to a TP program issuing an extract TP program list extension call.

WILDCRD="NO|yes"

Ignored for all connection types.
Default: WILDCRD="NO" 
Refresh: Yes

Specifies whether this HCICNTPT element represents a generic name for a set of TPs.

"NO"

Specifies not to use this HCICNTPT element's value for the TPNAME attribute as a generic name.

"YES"

Specifies to use this HCICNTPT element's value for the TPNAME attribute as a generic name. That is, the TPNAME becomes a prefix for all the real TP names that are used by the TPs themselves to register. This capability allows TPs to start by themselves, to be referred to by the generic name, and to each process a single conversation at a time.

/>

Close <HCICNTPT element. You must include a forward slash and right angle bracket (/>) XML construct to close the <HCICNTPT element. Failure to do so causes the document to not be well-formed and parsing to fail.