BCAMAPPL - define additional application names

The BCAMAPPL statement allows you to assign additional application names to the UTM application for client/server communication and distributed processing via LU6.1. Each application name defines a transport system endpoint that can be used to establish connections to the UTM application.

The primary application name of the UTM application is specified in the APPLINAME operand of the MAX statement. Please note the following:

• BS2000 systems:
  You may issue the BCAMAPPL statement only for additional BCAM names of the application. You must not issue a BCAMAPPL statement for the primary application name.

• Unix, Linux and Windows systems:

  • You will also need to issue a BCAMAPPL statement for the primary application name if you also wish to establish connections via this name to partner applications or clients.

  • Only a maximum of 1000 connections can be established at a time per application name. If more concurrent connections are needed by your application, you must define more than one application name.

The BCAMAPPL statement can be issued several times. However, to ensure that resources are not unnecessarily occupied, you should only generate as many BCAMAPPL statements (i.e. application names) as are necessary.

It is necessary to generate additional application names for your UTM application if:

• parallel connections via LU6.1 are to be defined to other applications (distributed processing). In this event, additional application names must be generated in at least one of the applications involved.

• communication with a partner is to be done via the socket interface (native TCP/IP). You will need a separate BCAMAPPL name (with T-PROT=SOCKET) for the communication via the socket interface. This name cannot be used for communication via other transport protocols.

• you select the transport protocol (not NEA) for a partner of a UTM application generated with PTYPE=APPLI, PTYPE=UPIC-R, or generated as a partner of a LU6.1 application.

• you establish multiplex connections to a partner of a UTM application.

• you want to communicate with a UTM application on Unix or Windows systems.

• you want to establish connections via the RFC1006 protocol. In this case you must define a separate BCAMAPPL name for the communication via RFC1006.

In all K-messages which contain the UTM application name as an insert, the name defined in the APPLINAME operand of the MAX statement will be displayed.

BCAMAPPL statement on BS2000 systems

BCAMAPPL

appliname     ,LISTENER-PORT=number only allowed and mandatory for T-PROT=SOCKET  [ ,SIGNON-TAC={ *NONE | tacname } ]                 [ ,T-PROT={ NEA | ISO | RFC1006 | SOCKET |                            (SOCKET [,*ANY | *USP | *HTTP] [,SECURE])} ]    [ ,USER-AUTH = *NONE | *BASIC ]

appliname	Additional BCAM name of the UTM application. appliname can be up to eight characters in length. appliname must not be identical to the application name you specified in MAX ...,APPLINAME= or in ACCESS-POINT..., TRANSPORT-SELECTOR=. appliname must be unique in the local system for each host.
LISTENER-PORT=	number Only permitted for T-PROT=SOCKET. In this case, it is mandatory to specify the LISTENER-PORT. LISTENER-PORT specifies the port number on which openUTM waits for external connection establishment requests. If LISTENER-PORT is generated together with T-PROT=(SOCKET,..., SECURE), then in addition to the port number defined with number, the port number number+1 is also assigned by the UTM application. The second port number is required for communication between the UTM application and the reverse proxy. All port numbers between 1 and 65535 are allowed. Each port number may only be used once in the local system. It may be when starting openUTM that some port numbers are already reserved by the system or other TCP/IP applications, or that privileged port numbers may not be used. In this case, the start of the UTM application is aborted.
SIGNON-TAC =	Specifies whether a sign-on service is to be started for connections that are established using the application names appliname (=transport system access point). If a sign-on service is to be started, you must specify the name of the transaction code via which the sign-on service is to be started.
*NONE	For connections to the UTM application that are to be established using the application name appliname, no sign-on service is to be started, regardless of whether the TAC is generated with KDCSGNTC or not. If  the T-PROT=(SOCKET,*ANY | *HTTP) is given for the BCAMAPPL, then the value *NONE has to be specified for SIGNON-TAC, if the TAC KDCSGNTC is generated for the application.
tacname	Name of the service TAC started via the sign-on service. The transaction code tacname must be generated using a TAC statement. In the TAC statement, you must not modify the following default settings for the transaction code: API = KDCS, CALL = FIRST or BOTH, ENCRYPTION-LEVEL = NONE, PGWT = NO, TACCLASS = 0, TYPE = D, no limitation on data access authorizations, i.e. the operands ACCESS-LIST and LOCK may not be specified For UPIC partners, the sign-on service is only started if UPIC=YES is generated in the SIGNON statement. In the case of UPIC partners, the signon service is not started when the connection is established. Instead, it is started before a UPIC conversation is started (see also SIGNON statement, OMIT-UPIC-SIGNOFF= parameter in section "SIGNON - control the sign-on procedure"). For LU6.1 partners, no sign-on service is started. tacname may not be assigned to a program (PROGRAM operand of a TAC statement) that is located in a load module generated with LOAD-MODE=ONCALL. Default: KDCSGNTC as far as it is generated in the application (KDCSGNTC = standard sign-on service; generated with a TAC statement) otherwise *NONE CAUTION! Those communication partners that establish their connection to the UTM application via the primary application name (generated in MAX APPLINAME=) can only have a sign-on service that is generated using the transaction code KDCSGNTAC.
T-PROT=	Transport protocols to be used on the connections to partner applications that are established through this application name.
NEA	An NEA transport protocol is used. Default: NEA
ISO	An ISO transport protocol is used. Whether or not an ISO transport connection can be established to this application and which transport protocol will actually be used depends on the generation of the transport system. As parallel connections are allowed for ISO transport connections although they are not supported by openUTM, openUTM accepts the connection of the contention winner (CON) or of the partner with the alphabetically smaller name pair (ptermname, processor name, PTERM statement) in case of a contention.
RFC1006	TCP/IP is used with the RFC1006 convergence protocol. RFC1006 is synonymous with T-PROT=ISO on BS2000 systems. T-PROT=RFC1006 or T-PROT=ISO must be used for communication with openUTM on Unix, Linux or Windows systems.
SOCKET	Native TCP/IP is to be used as the transport protocol, i.e. communication is to be handled via the socket interface. If you specify T-PROT=SOCKET, then you must define a port number in the LISTENER-PORT operand. You will find more information on SOCKET in the section "Providing address information". With sub-parameters the type of socket protocol can be speciified that is to be used on these connections.
*USP	The UTM socket protocol shall be used on connections of this transport system access point. *USP is the default value.
*HTTP	The HTTP protocol shall be used on connections of this transport system access  point.
*ANY	On connections of this communication end point both of the UTM socket protocol and the HTTP protocol are supported. WIth this configuration the protocol of a connection is determined by the protocol of the first message received.
*SECURE	When SECURE is specified as additional sub-parameter, then the TLS functionality of the secure socket layer is used for all communication on these connections. If SECURE is specified for an application in BS2000 systems, UTM starts an additional ENTER process with a reverse proxy for this application. The purpose of this proxy process is to accept SSL connections for the UTM application and pass them on to the UTM application. UTM passes a maximum of three listener port numbers to the reverse proxy process. This means that for a UTM(BS2000) application with a maximum of three BCAMAPPL statements, the attribute SECURE should be specified. If more than three BCAMAPPL statements with the SECURE attribute are required for an application, a user must create the start procedure of the reverse proxy process himself and start the process manually. The prerequisite for starting the reverse proxy process is that a job variable with the base name of KDCFILE is cataloged when the application is started. For details see the description for the use of such a job variable and of the reverse proxy process in generell in the manual "Using UTM Applications in BS2000 Systems" in the chapter "Starting UTM Applications".
USER-AUTH =	The USER-AUTH parameter specifies which authentication mechanism HTTP-clients must use for this application. The value that is set here for this parameter applies to all HTTP messages that are received using this application name and whose path specification is not mapped to a TAC using an HTTP-DESCRIPTOR statement. For the latter cases, the parameter USER-AUTH acts on the HTTP-DESCRIPTOR statement. If the UTM application is generated without users, only the value *NONE may be specified for USER-AUTH.
*BASIC	The Basic Authentication Scheme from RFC 2617 is to be used to transfer authentication data. If Basic Authorization is required for an HTTP request, but no Authorization Header is contained in the HTTP request, UTM requests authentication data using a response with status code 401 Unauthorized.
*NONE	If *NONE is specified, the client does not have to pass any authentication data. UTM uses the connection user for such a request if the client does not automatically send authentication information in the HTTP request. Default: *NONE

BCAMAPPL statement on Unix, Linux and Windows systems

On Unix, Linux and Windows systems the operands appliname, LISTENER-PORT (TCP/IP port number), T-PROT (transport protocols used) and TSEL-FORMAT (format identifier) are used to specify the address.

BCAMAPPL

appliname   [ ,LISTENER-ID=number ]  [ ,LISTENER-PORT=number ]  [ ,SIGNON-TAC={ *NONE | tacname } ]   [ ,T-PROT={ RFC1006 | SOCKET |              (SOCKET [,*ANY | *USP | *HTTP] [,SECURE])} ]    [ ,USER-AUTH = *NONE | *BASIC]]    [ ,TSEL-FORMAT={ T | E | A } ]

appliname	Additional name of the UTM application. appliname can be up to eight characters in length. appliname must not be identical to the application name you specified in ACCESS-POINT...,TRANSPORT-SELECTOR=. In addition, the name must be different from the application name that you specified in the BCAMAPPL operand of the CLUSTER statement. appliname must be unique throughout the network. KDCDEF creates a T-selectors from appliname for the transport system. The T-selectors is part of the transport address of the application that is used to address the application from partner applications when establishing a connection. Exception: appliname is only relevant internally in UTM for T-PROT=SOCKET, e.g. for the administration. The name only needs to be unique within the application.
LISTENER-ID=	number This assigns a listener ID to the application name as administrative information. Listener IDs can be specified for application names and access points. Further information can be found in the description of the ACCESS-POINT statement. You can use the listener IDs to distribute the network connections of the access points to different network processes. All connections of an access point are managed by the same network process. BCAMAPPL names with T-PROT=SOCKET (communication via the socket interface) comprise a separate set of numbers, i.e. the access points for communication via the socket interface are managed using different network processes than the access points for other transport protocols. If you do not specify a listener ID, then openUTM assigns the value 0 as the listener ID. All connections without a listener ID that are not established via the socket interface are combined into a single network process, and all connections without a listener ID that are established via the socket interface are combined into another single network process. Default value: 0 Minimum value: 0 Maximum value: 65535
LISTENER-PORT=	number Port number of the UTM application. All port numbers between 1 and 65535 are allowed. With T-PROT=RFC1006 and OPTION CHECK-RFC1006=YES and withT-PROT=SOCKET, a port number must be specified for LISTENER-PORT. In all other cases, the default value is 0 (no port number). A port number may only be used once per processor to listen for connections being established via the socket interface (SOCKET). If the default value is used (port number 0), the default port number assigned by PCMX is used internally. This can result in conflicts if, for example, the port is used by different applications.
SIGNON-TAC =	Specifies whether a sign-on service is to be started for connections that are established using the application names appliname (=transport system access point). If a sign-on service is to be started, you must specify the name of the transaction code via which the sign-on service is to be started.
*NONE	For connections to the UTM application that are to be established using the application name appliname, no sign-on service is to be started, regardless of whether the TAC is generated with KDCSGNTC or not. If  the T-PROT=(SOCKET,*ANY | *HTTP) is given for the BCAMAPPL, then the value *NONE has to be specified for SIGNON-TAC, if the TAC KDCSGNTC is generated for the application.
tacname	Name of the service TAC started via the sign-on service. The transaction code tacname must be generated using a TAC statement. In the TAC statement, you must not modify the following default settings for the transaction code: API = KDCS, CALL = FIRST or BOTH, ENCRYPTION-LEVEL = NONE, PGWT = NO, TACCLASS = 0, TYPE = D, no limitation on data access authorizations, or in other words, the operands ACCESS-LIST and LOCK may not be specified For UPIC partners, the sign-on service is only started if UPIC=YES is also generated in the SIGNON statement. In the case of UPIC partners, the signon service is not started when the connection is established. Instead, it is started before a UPIC conversation is started (see also SIGNON statement, OMIT-UPIC-SIGNOFF= parameter in section "SIGNON - control the sign-on procedure"). For LU6.1 or OSI TP partners, no sign-on service is started. Default: KDCSGNTC as far as it is generated in the application (KDCSGNTC = standard sign-on service; generated with a TAC statement) otherwise *NONE CAUTION! If the application name specified in appliname corresponds to the primary application name (generated in MAX APPLINAME=) then for SIGNON-TAC= you may specify KDCSGNTC (standard sign-on service), *NONE or leave it blank.
T-PROT=	Address formats of the T-selectors in the transport address. You can specify the following address formats for T-PROT.
RFC1006	Address format RFC1006 You will find more information on the RFC1006 address format in the section "PCMX documentation" (openUTM documentation). Default: RFC1006
SOCKET	Communication is done via the socket interface. No other address specifications are required other than T-PROT=SOCKET, LISTENER-PORT and appliname. You will find more information on SOCKET in the section "Providing addressinformation". With sub-parameters the type of socket protocol can be speciified that is to be used on these connections.
*USP	The UTM socket protocol shall be used on connections of this communication end point. *USP is the default value.
*HTTP	The HTTP protocol shall be used on connections of this communication end point.
*ANY	On connections of this communication end point both of the UTM socket protocol and the HTTP protocol are supported. WIth this configuration the protocol of a connection is determined by the protocol of the first message received.
*SECURE	If SECURE is also specified as an additional sub-parameter, then communication on these connections takes place using TLS via the Secure Socket Layer.
USER-AUTH =	The USER-AUTH parameter specifies which authentication mechanism clients must use for this application. The value that is set here for this parameter applies to all HTTP messages that are received using this application name and whose path specification is not mapped to a TAC using an HTTP-DESCRIPTOR statement. For the latter cases, the parameter USER-AUTH acts on the HTTP-DESCRIPTOR statement. If the UTM application is generated without users, only the value *NONE may be specified for USER-AUTH.
*BASIC	The Basic Authentication Scheme from RFC 2617 is to be used to transfer authentication data. If Basic Authorization is required for an HTTP request, but no Authorization Header is contained in the HTTP request, UTM requests authentication data using a response with status code 401 Unauthorized.
*NONE	If *NONE is specified, the client does not have to pass any authentication data. UTM uses the connection user for such a request if the client does not automatically send authentication information in the HTTP request. Default: *NONE
TSEL-FORMAT=	Format identifier of the T-selectors to be created from appliname. The format identifier specifies the encoding of the T-selector in the transport protocol. You will find more information in the section "PCMX documentation" (openUTM documentation).
T	TRANSDATA format (coding in EBCDIC) In this case appliname must be exactly 8 characters long and must not include lowercase letters.
E	EBCDIC format
A	ASCII format Default:     T   if the character set of appliname matches to the TRANSDATA format     E   in all other cases It is recommended for TNS-less operation via RFC1006 to explicitly specify a value for TSEL-FORMAT.