This topic describes each data interface command and its options. There are seven data interface commands:
Each of these data interface commands is described in detail in the following sections.
Establish a session between a client application and a CICSPlex SM Web User Interface server.
DATA/CONNECT >>-DATA/CONNECT--USERID=userid----------------------------------> >--+---------------------------------------------------+--------> '-PASSWORD=value-+--------------------------------+-' '-NEWPASS1=value--NEWPASS2=value-' >--+--------------+-------------------------------------------->< '-RECONN=value-'
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. You can also specify a new password. 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. Thus 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.
Although it does not contain any password information, the cookie represents access to the Web User Interface user session and should 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, normal Web User Interface server restrictions apply:
When a user session is no longer required, you can terminate it using the DATA/DISCONNECT command. As this terminates the user session, any browser sessions that have been launched by the client application are also disconnected. Similarly, if the user issues a signoff command in a launched 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:
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:
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 / (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 . (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= | This 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 : (colon). |
Data: The DATA/CONNECT command does not return any data records after the response header fields.
Release a result set created by a DATA/GET command.
This command requests the Web User Interface server to release all the resources for the result set associated with the specified stub. Although the server sends a response to the client application (that is, it does not make the request wait), it does not immediately discard the resources used by result set. The result set is marked as discarded and can no longer be accessed by the client. Instead of using a DATA/DISCARD and DATA/GET sequence for a new query, consider using a DATA/GET request that specifies an old stub that is no longer required.
The delay in discarding a result set means that the number of windows shown in the user sessions view (see Figure 17) can be higher than the number of windows actually active.
Data: The DATA/DISCARD command does not return any data records after the response header fields.
Disconnect a client application from a CICSPlex SM Web User Interface server.
This command enables the client application to initiate the termination of the user session established by a DATA/CONNECT data interface command.
All Web User Interface server sessions, including sessions started by the client application data interface, are subject to automatic signoff after a period of inactivity. This period is determined by the Web User Interface server initialization parameter, INACTIVETIMEOUT. When the original user session is terminated or replaced, the EYUTICKET value becomes invalid and is ignored by the Web User Interface server.
Data: The DATA/DISCONNECT command does not return any data records after the response header fields.
None.
Retrieve the records created in a result set by a previous DATA/GET command.
This command retrieves records from the result set identified by the stub value returned to your client application in response to a DATA/GET or DATA/FETCH command.
Header field | Description |
---|---|
COUNT= | The number of records returned in this response, which can be zero. |
OBJECT= | The name of the CICSPlex SM resource. |
REASON= | The CICSPlex SM reason code for the FETCH (the EYUDA value). |
RESPONSE= | The CICSPlex SM API response code for the FETCH (the EYUDA value). |
STUB= | The STUB header for use on subsequent requests against the result set. |
USERID= | The user ID of the session. |
The contents of the records selected from result set are contained in additional records in the data interface response, following the response header record (see Figure 41 for an illustration of an HTTP response package). Each data record encodes a single result set record, in the order that they appeared in the result set, starting from the record specified by the POSITION= option in the DATA/FETCH request.
Each result set record is described as a series for attribute-value pairs. The attribute name corresponds to the attribute name in the CICSPlex System Manager Resource Tables Reference and the value is represented as described above. The order that theses attributes appear in a particular result set record is undefined and the client application has to search for specific attributes by attribute name. If the FIELDS= option is specified, the DATA/FETCH command returns only the attributes named by the FIELDS= option, in the order specified by the client. If the FIELDS= option is not specified, all attributes of the resource will be returned and the order that these attributes appear in a particular result set record is undefined. In this case, the client application must search for specific attributes in each record by attribute name.
If a requested attribute on a DATA/GET request is not valid for the release of CICS from which the result set is created, the attribute is not included in the data interface record.
When your client application is finished with a result set, it can use the DATA/DISCARD command with the correct STUB value to discard it.
The list of attributes must be separated by a comma and terminated with a period. You can specify any attribute listed in the CICSPlex System Manager Resource Tables Reference for the resource type, including EYU_CICSNAME. There must be no white space characters between the attribute names and the separating commas or period. Any characters in the FIELDS= value that appear after the period will be ignored.
For example, to request that only the originating CICS name, the transaction ID, and enable status attributes be retrieved for each local transaction (LOCTRAN) record, specify:
FIELDS=EYU_CICSNAME,TRANID,STATUS.
If an attribute name is repeated in the list, the attribute will be repeated in the response records. However, the total number of attributes specified in the attribute list must not exceed the number of attributes defined by the CICSPlex System Manager Resource Tables Reference for the resource type.
If the attribute list is not formatted correctly, contains too many attributes, or contains an unknown attribute name, the DATA/FETCH command RESPONSE header will contain INVALIDPARM and the REASON header will contain FIELDS. No data records will be returned.
If the FIELDS= option is not specified, the response will contain all the attributes of each record in an undefined order.
Request the CICSPlex SM Web User Interface server to create a result set of records that satisfy a query.
DATA/GET >>-DATA/GET--OBJECT=resource_name-------------------------------> .-----------------------------------------------------------------. V | >----+-------------------------------------------------------------+-+--> '-A_attributeName=character_string-+------------------------+-' '-O_attributeName=number-' >--+-----------------------------------------------------+------> +-CMASCONTEXT=character_string------------------------+ '-CONTEXT=character-string-+------------------------+-' '-SCOPE=character-string-' >--+----------------------------------+-------------------------> '-P_parameterName=character-string-' >--+-----------------------+----------------------------------->< '-STUB=character_string-'
Initially, you issue a DATA/GET request for a new result set of records without specifying a STUB option on the command. The response from the server includes a STUB header identifying the result set.
You can reuse a results set by issuing a another DATA/GET command that specifies a previous stub value. This has the effect of discarding the old results and reusing the resources to hold the results of the new DATA/GET request.
The result of a DATA/GET command for STATUS OK is shown in Table 16.
Header field | Description |
---|---|
COUNT= | The number of records in the results set that match the query. This can be a zero value. |
OBJECT= | The CICSPlex SM resource name, as specified on the DATA/GET command. |
REASON= | The CICSPlex SM API reason code, where applicable. |
RESPONSE= | The CICSPlex SM API response code. |
STUB= | The stub value to be used for the next request relating to this query. This can be another GET, or a FETCH or DISCARD command. |
USERID= | The user ID signed on to the Web User Interface Server session used for this request. |
The CICSPlex SM Web User Interface server manages each active data interface result set as a single-user session window. Each user session can have at anyone time a maximum of 64 active windows, which are shared between the client application data interface and the HTML interface.
Data: The DATA/GET command does not return any data records after the response header fields. The command creates a result set from which a subsequent DATA/FETCH command can retrieve records.
The following attribute datatypes can be used as filters:
See the CICSPlex System Manager Resource Tables Reference for details of all the CICSPlex SM resource tables.
See also Access to the Web User Interface for a discussion about selection criteria and Data representation for information about data representation.If you omit this option, the server uses the last CONTEXT for the specified STUB, or the server default if you do not specify a STUB on the command.
If you omit this option, the server uses the last CMASCONTEXT for the specified STUB, or the server default if you do not specify a STUB on the command.
See the CICSPlex System Manager Resource Tables Reference for details of all the CICSPlex SM resource tables.
Not all resources have parameters associated with them. See the CICSPlex System Manager Resource Tables Reference for details of all the CICSPlex SM resources and information about their parameters, if any. See also Data representation for information about data representation.
Request the CICSPlex SM Web User Interface server to create a result set containing selected descriptive records (metadata) for a resource table
DATA/GETDEF >>-DATA/GETDEF--------------------------------------------------> >--+-----------------------------------------------+------------> +-ATTRIBUTE=attribute_name----------------------+ '-ACTION(data-value)-+------------------------+-' '-ACTIONPARM(data-value)-' >--OBJECT=resource_name--+---------------------------+----------> '-RESOURCE=character-string-' >--+-----------------------+----------------------------------->< '-STUB=character_string-'
Initially, you issue a DATA/GETDEF request for a new result set of metadata records without specifying a STUB option on the command. The response from the server includes a STUB header identifying the metadata result set.
You can reuse a result set by issuing another DATA/GETDEF or DATA/GET command that specifies a previous stub value. This has the effect of discarding the old results and reusing the resources to hold the results of the new DATA/GETDEF or DATA/GET request.
The result of a DATA/GETDEF command for STATUS OK is shown in Table 16.
Header field | Description |
---|---|
COUNT= | The number of records in the results set that match the query. This can be a zero value. |
OBJECT= | The type of metadata to be retrieved for the resource table specified on the RESOURCE option. |
REASON= | The CICSPlex SM API reason code, where applicable. |
RESPONSE= | The CICSPlex SM API response code. |
STUB= | The stub value to be used for the next request relating to this query. This can be another GETDEF, a GET, a FETCH, or a DISCARD command. |
USERID= | The user ID signed on to the Web User Interface Server session used for this request. |
The CICSPlex SM Web User Interface server manages each active data interface result set as a single-user session window. Each user session can have at anyone time a maximum of 64 active windows, which are shared between the client application data interface and the HTML interface.
Data: The DATA/GETDEF command does not return any data records after the response header fields. The command creates a result set from which a subsequent DATA/FETCH command can retrieve records.
Depending on which CPSM metadata table is named on the OBJECT parameter, this value can be the 1- to 12-character name of a specific attribute or an asterisk (*), for all attributes in the resource table. If you do not specify the ATTRIBUTE option for an OBJECT that does not require it, data is retrieved for all attributes in the resource table.
See the CICSPlex System Manager Resource Tables Reference for details of all the CICSPlex SM resource table attribute names.If you specify the ATTRIBUTE parameter, the resource value must be the 1- to 8-character name of a specific CICSPlex SM resource table. Otherwise, you can specify a value of asterisk (*) to retrieve data for all resource tables.
Requests a RACF®, or other external security manager (ESM), PassTicket from the CICSPlex SM Web User Interface server.
Access to the Web User Interface explains how you can access the Web User Interface through a Web browser. For example, a client application using the data interface might want to launch a Web browser window to allow the user to carry out some activities not supported directly by the client application. However, because the Web browser is a separate application it does have the client's cookie, which means the user of the client application would have to sign on separately to the Web User Interface server through the browser.
The DATA/PASSTICKET command provides a mechanism by which a client application can achieve an authenticated browser launch without requiring the user to perform another signon. This mechanism is in two parts:
When the client application receives a PassTicket, it can start a Web browser using the HTTP POST method to send the signon details for the user. The POST request includes the variables matching the options of the DATA/CONNECT command, including USERID=value, RECONN=J, and PASSWORD=. However, on the PASSWORD= option, you specify the PassTicket value in place of the password. You can specify the required menu, view, or object on the URL path of the browser start request. Include in the POST request body any additional query variables for the launch request; for example, CONTEXT.
If the DATA/PASSTICKET command completes with STATUS OK, the command response returns the following additional header field:
Header field | Description |
---|---|
PASSTICKET= | The PassTicket generated by the ESM. This PassTicket is for the current application and user ID, and must be protected.. |