The application program is started using the START-EXECUTABLE-PROGRAM command.
The following then applies:
If shareable parts of the application or the runtime systems required by the application are to be loaded into system memory, then this must be initiated by the administrator before the start of the application program.
The START-EXECUTABLE-PROGRAM command loads the statically linked part of the application program into working memory. All load modules of the application program that were generated with LOAD-MODE=STARTUP or LOAD-MODE=(POOL,...) are loaded at the start of the application as independent units.
If individual load modules cannot be loaded, then the start of the application is generally resumed. If there is a branch to a program that could not be loaded while the application is running, then this leads to a BADTACS event service call or to a PEND ER. If the MSGTAC, SIGNON event services or the START, SHUT, INPUT and FORMAT event exits or the administration program unit or AREAs could not be loaded, then the start of the application is aborted with an error message.
openUTM checks on the basis of the generation information whether the application program loaded in this task matches the program started in tasks started earlier when an additional task is started for the application and also after a PEND ER. If the data does not match, then openUTM aborts the start of the follow-up task with an error message.
Start commands for the application program
The application program is started with:
/START-EXECUTABLE-PROGRAM FROM-FILE = *LIB-ELEM - / ( LIB = llm-plamlib - / , ELEM = start-llm - / )
The application program start-llm must be made available as a type L element in a program library with name llm-plamlib .
If you have generated a load module with ALTERNATE-LIBRARIES=YES, you must assign a link name (BLSLIBnn with 00<=nn<=99) to the library of the respective runtime system before the application program starts. While the application is running, you can output a DBL list of the dynamic load processes with the BS2000 command
/MODIFY-DBL-DEFAULT PRIORITY=*FORCED, SCOPE=*ALL(PROGRAM-MAP=...).
Because this delays the start process and the program exchange, you should only use this when debugging or when an error occurs.
If parts of the application program are to be loaded later, then you must specify the following operands at the start of the application program:
/ ,DBL-PARAMETERS = *PARAMETERS( - / ,LOADING = *PARAMETERS( - / PROGRAM-MODE = *ANY - / ,LOAD-INFORMATION = *REFERENCES) - / ,RESOLUTION = *PARAMETERS( - / ALTERNATE-LIBRARIES = *BLSLIB## - / ,AUTOLINK = *ALTERNATE-LIBRARIES ) - / ,ERROR-PROCESSING=*PARAMETERS( - / UNRESOLVED-EXTRNS=*DELAY - / ,ERROR-EXIT = *NONE))
The following list shows the options available to you for influencing the autolink function:
If you do not need the Autolink function during the start phase and you have unresolved external references in the start LLM, then you should suppress the function with AUTOLINK=*NO.
AUTOLINK=*YES,ALTERNATE-LIBRARIES=*NO causes the library from the load call to be searched.
AUTOLINK=*ALTERNATE-LIBRARIES,ALTERNATE-LIBRARIES=*TASKLIB/*BLSLIB## causes the TASKLIB and/or the BLS libraries to be searched.
AUTOLINK=*YES,ALTERNATE-LIBRARIES=*TASKLIB/*BLSLIB## causes the library from the load call and the TASKLIB and/or BLS libraries to be searched.
Even if the start LLM does not contain any unresolved external references at the start, the DBL search in the shared code should be suppressed with the start operand SHARE-SCOPE=*NONE.
openUTM first loads all load modules that are to be maintained as shareable in common memory pools (LOAD-MODE=POOL) at the start of the application. First, the common memory pools are loaded that were generate with SCOPE=GLOBAL, and then those with SCOPE=GROUP are loaded, in each case in the order specified in the generation. Then openUTM loads all load modules that were generated with LOAD-MODE=STARTUP also in the order in which you specified them in the LOAD-MODULE statement.
Load modules that were generated with LOAD-MODE=ONCALL are only loaded once a program unit of this load module is called.
Different UTM applications should be started under different BS2000 user IDs, if possible, to prevent errors that occur due to having the same module names in shareable parts. Modules that are used by several applications should therefore be loaded into global common memory pools or in nonprivileged subsystems.
A sample start procedure is also supplied with openUTM, see section "Sample procedures".
Starting an application with TLS connections
If a BCAMAPPL with T-PROT=(SOCKET,...,SECURE) has been generated for a UTM application, communication takes place via this transport system access point via the Transport Layer Security (TLS).
When an application generated in this way is started, openUTM starts an additional task in which a reverse proxy is executed, which is used to handle all TLS connections in the form of a TLS Termination Proxy. The task with the reverse proxy is started with the job name "SSLPROXY". When the application is terminated, the reverse proxy is also terminated.
The reverse proxy writes a SYSOUT file with the following pattern: <APPLNAME>.<JOBNAME>.<TSN>.YYYY-MM-DD-HH:MM:SS . This file is toggled at midnight.
The reverse proxy communicates with HTTPS clients via TLS connections and with the UTM application via a host-local socket connection. The reverse proxy must run on the same computer as the UTM application.
As a prerequisite for starting a reverse proxy for a UTM application, a job variable with the base name of KDCFILE must be cataloged. The product JV ("job variable") is required for this. This job variable is used for the orderly termination of the proxy process.
openUTM starts the task with the reverse proxy via an ENTER procedure that is stored with the name START-SSL-PROXY in the SYSLIB.UTM.070.SSL library. If required, this procedure file can be adapted to the needs of the user.
In this case the procedure should be fetched from the library and adapted accordingly.
When the application is started, the new start parameter "START-SSL-PROC" is specified with the name of this procedure and any desired sequence parameters. The required procedure parameters such as filebasename, listener ports, etc. are supplied by openUTM.
If no start parameter is specified, the procedure is started from the above library.
The reverse proxy task reads SSL configuration parameters from the SAM file.
<filebase>.SSL.CONF
Such a file with the name FILEBASE.SSL.CONF is delivered by openUTM as an example. This file is also located in the SYSLIB.UTM.070.SSL library. It must be used by the user for his application and copied to the ID in which the UTM application is started. Before starting the application, the user must adapt the entries in this file to his environment and requirements.
The following parameters can be configured in this file.
CACertificateFile
The CACertificateFile option specifies a file that contains the CA certificates in PEM format required for the authentication of the reverse proxy.
CipherSuite
The CipherSuite option specifies a preferred list of encryption procedures
If this option is not specified, a default preference list is used.
DSACertificateFile
The DSACertificateFile option specifies a file that contains the DSA-based X.509 server certificate in PEM format.
This file can also contain the private DSAServer key. As a rule, however, the certificate and key are stored in separate files. In this case, the key file is specified using the DSAKey-File option.
DSAKeyFile
The DSAKeyFile option specifies a file that contains the private DSA server key in PEM format.
If both the X.509 server certificate and the private server key are contained within the same file, the RSAKeyFile option need not be specified.
RSACertificateFile
The RSACertificateFile option specifies a file that contains the RSA-based X.509 server certificate in PEM format.
This file can also contain the private RSA server key. As a rule, however, the certificate and key are stored in separate files. In this case, the key file is specified using the RSAKeyFile option.
RSAKeyFile
The RSAKeyFile option specifies a file that contains the private RSA server key in PEM format.
If both the X.509 server certificate and the private server key are contained within the same file, the RSAKeyFile option need not be specified.
ECDSACertificateFile
The ECDSACertificateFile option specifies a file that contains the ECDSA-based X.509 server certificate in PEM format.
ECDSAKeyFile
The ECDSAKeyFile option specifies a file that contains the private ECDSA server key in PEM format.
Further details on the syntax and meaning of the options, as well as on generating the certificate and key files are described in the manual "interNet Services User V3.4B" in chapter "SSL", as well as in the manual "interNet Services Administrator V3.4B" in chapter "TELNET Configuration".