DATA/CONNECT

Establish a session between a client application and a CICSPlex® SM Web User Interface server.

DATA/CONNECT

Description

The DATA/CONNECT command enables you obtain a Web User Interface user session from a client application. If the Web User Interface server is running with security enabled, a connection command must include the correct password or password phrase. You can sign on with either a valid password or a valid password phrase. If the password you enter is between 1 and 8 characters, it is treated as a standard password. If the length is between 9 and 100 characters, it is treated as a password phrase. You can also specify a new password or password phrase. However you cannot set a new password phrase by using a standard password for authentication, nor can you set a new password by using a password phrase for authentication.

Because the DATA/CONNECT command can contain password details, the server accepts connection request using only the HTTP POST method.

A user ID can have only one session with a specific Web User Interface server. A user ID signed on directly to the CICSPlex SM Web User Interface cannot also sign on from a client application using the data interface. However, an existing session can be taken over using the RECONN option.

When the user session has been established, the response to the DATA/CONNECT command includes an HTTP cookie, which acts as a ticket to the session. The client application must retrieve the cookie from the response and include it in all subsequent requests to the Web User Interface server for the user session.

Note: The cookie name and value are a black box to the client application, which should return the cookie to the server unaltered. The client application should also assume that the cookie name and value are variable length to protect against change in a future release of the data interface

Although it does not contain any password information, the cookie represents access to the Web User Interface user session and must be protected accordingly. The client must honor the restrictions set out in the HTTP cookie response header. Do not send the cookie to any other host name or path and do not write the cookie to a file.

A data interface client is permitted to create multiple connections (either to different servers for the same user ID, or for different user IDs on the same server), provided that the correct cookie is sent for each request. However, the following normal Web User Interface server restrictions apply:

Only one active session for a specific user ID on each server is permitted.
The total number of sessions on a Web User Interface server is limited by the server initialization parameter, MAXUSERS.

When a user session is no longer required, you can end it using the DATA/DISCONNECT command. As this ends the user session, any web browser sessions that have been launched by the client application are also disconnected. Similarly, if the user issues a SIGNOFF command in a launched web browser window, the client application session is also disconnected.

If the DATA/CONNECT command completes with STATUS OK, the DATA/CONNECT command can also return the following additional header fields:

Table 1. Data returned on DATA/CONNECT command response header
Header field	Description
DATEFORMAT=	Identifies the format being used by this session to represent dates on Web User Interface displays. The data interface client must use this format for date filters when launching an HTML view. Possible values are: YYMMDD DDMMYY MMDDYY YYYYMMDD DDMMYYYY MMDDYYYY Note: The format used for data interface requests and responses is always `YYYYMMDD`.
DATESEPARATOR=	Identifies the character being used by this session to separate date elements on Web User Interface displays. The data interface client must use this character for date filters when launching an HTML view. Note: The character used for data interface requests and responses is always a forward slash (`/` ).
DECIMALSEPARATOR=	Identifies the character being used by this session to denote the decimal point on Web User Interface displays. The data interface client must use this character for numerical filters when launching an HTML view. Note: The character used for data interface requests and responses is always a period (`.`).
DAYSLEFT=	Gives the number of days until the user's password expires. This header field is present only if security is enabled in the Web User Interface server.
INTERFACELEVEL=	Indicates the support level of the client application data interface implemented by the Web User Interface server, as a decimal integer. The requirement of a specific INTERFACELEVEL value is documented within the descriptions of the appropriate data interface commands and options. To use these options, the client should examine the INTERFACELEVEL value to ensure it is greater than or equal to the support level required. If the INTERFACELEVEL header is not present, the client must assume the value, 0.
LASTUSETIME=	Gives the date and time the user ID was last used, in the form `yyyy/mm/dd hh:mm:ss`. This header field is present only if security is enabled in the Web User Interface server.
TCPIPHOSTNAME=	Returns the fully-qualified host name of the Web User Interface server as specified on the Web User Interface TCPIPHOSTNAME initialization parameter.
TIMESEPARATOR=	Identifies the character being used by this session to separate hours, minutes and seconds on Web User Interface displays. The data interface client must use this character for time filters when launching an HTML view. Note: The character used for data interface requests and responses is always a colon (`:`).

The DATA/CONNECT command does not return any data records after the response header fields.

Note: If the client application does not issue a request on a user session for a period longer than the time specified by the Web User Interface INACTIVETIMEOUT parameter, all web browser windows and client applications are automatically disconnected. Whenever the server receives a request, either from a client application or a web browser window it has launched, the server resets the clock measuring the inactive time on a user session.

Options

NEWPASS1=value

Specifies a new password or password phrase if you want to change the current password or password phrase. Omit this option if you do not want to change the password. If you specify a value for PASSWORD that is 8 characters or less, it is a standard password and the value for NEWPASS1 must also be 8 characters or less. If you specify a value for PASSWORD that is between 9 and 100 characters or less, it is a password phrase and the value for NEWPASS1 must also be between 9 and 100 characters.

Note: The minimum length of a password phrase can be controlled by the RACF® password phrase exit ICHPWX11. When ICHPWX11 is present and allows it, the password phrase can be between 9 and 100 characters. When ICHPWX11 is not present, the password phrase must be between 14 and 100 characters.

NEWPASS2=value

Specifies the new password or password phrase again to validate that it is the same as the value on NEWPASS1. This can be omitted.

PASSWORD=value

Specifies the user's password or password phrase, for signing on to a Web User Interface server. The PASSWORD option is not required if the Web User Interface server is running with security inactive (that is SEC=NO is specified as a CICS® system initialization parameter). If the password you enter is between 1 and 8 characters, it is treated as a standard password. If the length is between 9 and 100 characters, it is treated as a password phrase.

RECONN={N |J|Y}

Specifies the reconnection action required if the user session is already active:

N: Do not reconnect by destroying the existing user session and connecting the user of the client application on a new session.
J: Join the existing user session
Y: Destroy the existing user session and create a new session for the specified user ID.

USERID=value

Specifies the user ID for which a session is to be created. This must match the user ID specified in the base part of the DATA/CONNECT command in the URL.

STATUS values

BADCOMMAND: The command passed to the data interface is not recognized.
CICSESMNOTINITIALIZED: The external security manager has not been initialized. Ensure that the CICS external security manager is initialized.
CONNECTIONFAILURE: The attempt to connect to the CICSPlex SM application programming interface (API) for the new user session has failed.
ESMNOTRESPONDING: The external security manager is not responding. Ensure that the external security manager is running correctly.
GROUPLENGERR: The length of the group is incorrect. Specify a group that is of a supported length.
GROUPUNKNOWN: The Web User Interface server is running with sign-on security enabled, and the group specified is not known to the ESM.
INCOMPATIBLEPASSWORDS: A password cannot be used to change a password phrase and a password phrase cannot be used to change a password. Specify a new password if changing a password and a new password phrase if changing a password phrase.
MAXUSERS: The maximum number of users permitted to be signed on to the Web User Interface server has been reached. The maximum number of users is defined by the server initialization parameter MAXUSERS.
NEWPASSWORDINVALID: The new password or password phrase does not satisfy the rules for passwords or password phrases, as defined by the host system external security manager (ESM).
NEWPASSWORDLENGERR: The length of the new password is incorrect. Specify a new password or new password phrase that is of a supported length.
NEWPASSWORDMISMATCH: The values specified on NEWPASS1 and NEWPASS2 are different, and these values must be the same to change successfully an existing password or password phrase.
PASSWORDEXPIRED: The specified password or password phrase is out-of-date. Specify a new password or password phrase using NEWPASS1 and NEWPASS2.
PASSWORDLENGERR: The length of the password is incorrect. Specify a password or password phrase that is of a supported length.
PASSWORDREQUIRED: The password or password phrase is missing from the DATA/CONNECT request. The Web User Interface server is running with sign-on security enabled, and therefore a password or password phrase is required.
RECONNECTREQUIRED: The user is already signed on but the RECONN option did not specify J or Y.
UNAUTHORIZED: Either the supplied USERID or PASSWORD is incorrect.
USERIDCONTAINSBLANKS: The user ID contains blank characters in an invalid position. Specify a valid user ID that conforms to the user ID rules defined by the external security manager.
USERIDLENGERR: The length of the user ID is incorrect. Specify a user ID that is of a supported length.
USERIDREQUIRED: The DATA/CONNECT command requires a user ID to establish a session with the Web User interface.
USERIDREVOKED: The Web User Interface server is running with sign-on security enabled, but the external security manager has revoked the user ID.