Without using WebSphere MQ, a CICS transaction can be started in several ways, including:
A transaction that has been invoked at a terminal can subsequently issue commands such as EXEC CICS CONVERSE, EXEC CICS SEND MAP and EXEC CICS RECEIVE MAP in a conversation or pseudoconversation with a terminal user.
The CICS bridge can emulate any of the these ways of starting CICS transactions. It can also emulate a terminal user sending and receiving screens of data from the transaction. These emulations are achieved by using CICS bridge vectors, which represent the EXEC CICS command being emulated and provide any data that is needed. The data needed by a CICS transaction accompanies inbound messages, and the data needed by a CICS bridge application accompanies outbound messages.
Use vectors to represent EXEC CICS commands in request and reply messages. Vectors are represented in bridge messages by strings of numeric characters known as vector descriptors, for example 0402. Each vector descriptor is the CICS EIBFN value of the EXEC CICS command that it represents. For example, 0402 is the EIBFN value for EXEC CICS RECEIVE, and also the vector descriptor of the RECEIVE vector. Vectors are further qualified by the letters I and O to show whether they are inbound (to the bridge) or outbound (from the bridge).
An outbound message can contain a request vector or a reply vector. These descriptions do not mean that they go to the request queue or the reply queue; all outbound messages go to the reply queue. A CICS transaction uses a request vector to request data from the WebSphere MQ bridge application that is acting as the virtual terminal. A CICS transaction uses a reply vector when it does not expect any data back. No such distinction is made for inbound vectors.
The following vectors are available. To get the CICS command that each represents, prefix the vector name with EXEC CICS.
Each of these vectors is an architected structure followed by variable length data. For details of the structures, refer to the CICS Internet and External Interfaces Guide for CICS V1.2, or CICS External Interfaces Guide for CICS V1.3.
The term 'CICS 3270 bridge' is used here to mean all non-DPL CICS transactions.
These examples show the possible structures of CICS 3270 bridge inbound messages.
-------------- | MQMD | MQCIH | --------------
Set the field MQCIH.TransactionId to the name of the transaction you want to start. Set the other fields in the CIH to values that are appropriate for the application.
------------------------------- | MQMD | MQCIH | BRMQ structure | -------------------------------
For example, an inbound RECEIVE MAP vector can represent an action where the user has only pressed a PF key. In this case, a field within the BRMQ structure specifies which AID key had been used, but no data follows the BRMQ structure.
-------------------------------------- | MQMD | MQCIH | BRMQ structure | data | --------------------------------------BRMQ structure represents any of the inbound vector structures RECEIVE, RECEIVE MAP, CONVERSE or RETRIEVE.
Outbound messages from the bridge have one of three structures, depending on whether an error occurred. Although only a single vector is shown in each of these examples, messages can contain several concatenated vectors, except when an error occurs.
------------------------------- | MQMD | MQCIH | BRMQ structure | -------------------------------
Even if an application abends, this is still regarded as normal completion by the bridge. The abend code issued by the application is given in the MQCIH.
-------------------------------------- | MQMD | MQCIH | BRMQ structure | data | --------------------------------------BRMQ structure represents any of the architected outbound reply or request vector structures.
------------------------------ | MQMD | MQCIH | CSQC* message | ------------------------------CSQC* message represents an error message that indicates the error type. The value of field MQCIH.Format is set to MQFMT_STRING, to ensure that the message can be properly converted if the final destination uses a different CCSID and encoding. The MQCIH also contains other fields that you can use to diagnose the problem.
Notes:
If the transaction issues a command that causes a request vector to be generated, the request vector will always be the last one in the message.
Application programming for the CICS 3270 bridge is usually more complex than application programming for the DPL bridge for these reasons:
If you are unfamiliar with the terminology used for describing application data structures, you should now refer to the section Application data structure terminology.
You must make sure every inbound message that is sent to the CICS 3270 Bridge includes a vector structure after the CIH, except when you start a transaction with no data.
The vector structure definitions are available in C-language header file dfhbrmqh.h and COBOL copybook DFHBRMQO. You should include these in any application that uses the bridge. These members are only provided with CICS Transaction Server on z/OS. If you wish to create your application on another platform, you must copy them to that environment.
All the vectors have a common header, but their structures differ. Details of the structures are given in the CICS Internet and External Interfaces Guide for CICS V1.2, or the CICS External Interfaces Guide for CICS V1.3. You will need to refer to these books when you are developing your bridge applications.
You are recommended also to obtain a copy of CICS SupportPac CA1E "CICS Bridge Passthrough" as an aid to analyzing the logic of your existing CICS transactions, and to help plan your WebSphere MQ CICS 3270 Bridge applications. You can use the SupportPac to test whether CICS transactions work in a Bridge environment without having to write any application code. It also enables you to display and capture the inbound and outbound data flows, to study how messages must be structured, and what values need to be inserted into fields in the MQCIH and the vectors.
This simple example illustrates how you might write applications for the CICS 3270 Bridge; it shows how to invoke a transaction that would normally be started by entering its identifier and some command line arguments at a CICS terminal:
This example shows how an application can start a transaction, in this case CEMT, that expects to receive command line arguments when it is invoked.
When the CEMT task starts, it issues EXEC CICS RECEIVE to receive any command line arguments that follow its identifier. The application that emulates the command line invocation must therefore start CEMT with a RECEIVE vector that contains appropriate values in the vector structure, and also include the command line values. The following C-language code fragment shows how the inbound message can be constructed.
/* #includes */ #include cmqc.h /* WebSphere MQ header */ #include dfhbrmqh.h /* Vector structures */
·
·
·
/* #defines */ #define CMDSTRING "CEMT I TASK" /* Command string */ #define RCV_VECTOR "0402" /* Vector descriptor */ #define INBOUND "I " /* Inbound type */ #define VERSION "0000" /* Vector version */ #define YES "Y " /* YES indicator */ #define NO "N " /* NO indicator */
·
·
·
/* Data declarations */ /* AID indicator value */ const char AID[ 4 ] = { 0x7d, ' ',' ',' ' } ; MQMD mqmd ; /* Message descriptor */ MQCIH mqcih ; /* CICS information header */ brmq_vector_header brvh ; /* Standard vector header */ brmq_receive brrcv ; /* RECEIVE vector structure */ MQCHAR * MsgBuffer ; /* Message buffer pointer */
·
·
·
/* allocate storage for the message buffer. Note that the */ /* RECEIVE vector structure includes space for the standard */ /* vector header. */ MsgBuffer = malloc(sizeof(MQCIH) + sizeof(brrcv) + strlen(CMDSTRING) ) ;
·
·
·
/* Initialize fields in the MQMD as required */ /* Initialize fields in the MQCIH as required, including: */ strncpy(MQCIH.TransactionId, "CEMT", strlen("CEMT"));
·
·
·
/* Initialize fields in the RECEIVE vector header: */ brvh.brmq_vector_length = sizeof(brrcv) + strlen(CMDSTRING) ; strncpy(brvh.brmq_vector_descriptor, RCV_VECTOR, strlen(RCV_VECTOR)) ; strncpy(brvh.brmq_vector_type, INBOUND, strlen(INBOUND)) ; strncpy(brvh.brmq_vector_version, VERSION, strlen(VERSION)) ; /* Initialize fields in the RECEIVE vector structure: */ strncpy(brrcv.brmq_re_transmit_send_areas, YES, strlen(YES)) ; strncpy(brrcv.brmq_re_buffer_indicator, NO, strlen(NO)) ; strncpy(brrcv.brmq_re_aid, AID, sizeof(brrcv.brmq_re_aid)) ; brrcv.brmq_re_data_len = strlen(CMDSTRING) ;
·
·
·
/* Copy the MQCIH to the start of the message buffer */ memcpy(MsgBuffer, &mqcih, sizeof(MQCIH)) ; /* Append the RECEIVE vector to the CIH */ memcpy(MsgBuffer + sizeof(MQCIH), brrcv, sizeof(brrcv) ) ; /* Overlay the standard vector header on the RECEIVE vector */ memcpy(MsgBuffer + sizeof(MQCIH), brvh, sizeof(brvh) ) ; /* Append the command string to the vector structure */ strncpy(MsgBuffer + sizeof(MQCIH) + sizeof(brrcv), CMDSTRING, strlen(CMDSTRING)) ; /* The message buffer is now ready for the MQPUT */ /* to the Bridge Request Queue. */
·
·
·
The outbound message that is returned to the reply queue contains a SEND reply vector with data in terminal control format - your application needs to know this when it analyzes the data that it receives.
If your bridge application is running just a single transaction, you should set the value of MQCIH.UOWControl to MQCUOWC_ONLY. However, if your application is sending and receiving multiple messages, you must handle unit of work management differently for the CICS 3270 bridge
A transaction can split itself into multiple units of work by issuing EXEC CICS SYNCPOINT, but you cannot group transactions into a single unit of work. Always set the value of MQCIH.UOWControl to MQCUOWC_ONLY in the first message, even when many messages are sent by your application. You should set MQCUOWC_CONTINUE in messages supplying additional data to the transaction. If you wish to terminate the transaction, set the value of MQCIH.CancelCode to a four-character abend code.
CICS Basic Mapping Support (BMS) provides a way for CICS applications to support a number of different terminal types. When the application issues EXEC CICS SEND MAP, BMS merges terminal-specific control data with the application data to produce a 3270 data stream that can be displayed at the terminal. When the application issues EXEC CICS RECEIVE MAP, application data is extracted from an inbound 3270 data stream and returned to the application.
A BMS map for a CICS application is created by assembling a set of BMS macros that define the characteristics of fields that are required for the display. One of the outputs from map assembly is a copybook that maps the display fields to an ADS. The CICS application must include the copybook in its data definitions so that it can address the fields in the map symbolically. The application data in a SEND MAP, and expected by a RECEIVE MAP, is mapped directly to the ADS in the copybook.
When the transaction runs under the CICS bridge, EXEC CICS SEND MAP and EXEC CICS RECEIVE MAP commands cause SEND MAP and RECEIVE MAP vectors to be generated in outbound messages. Instead of a 3270 data stream, these vectors contain ADSs equivalent to those used by the CICS application to address fields in the map.
The format of the ADS is unique for each map. It is described by a copybook created as part of map generation. Without this copybook it is difficult to interpret the data. Usually WebSphere MQ applications include the BMS copybooks so that they can create RECEIVE MAP data, and interpret SEND MAP data. However, you can write an application without the specific BMS copybooks. The format of the data is described by a structure known as the ADS Descriptor (ADSD). The ADSD is added to the end of a SEND MAP vector, and it describes the format of the ADS in the vector. The ADSD contents include the names, positions and lengths of the fields in the ADS. An ADSD can also be sent on a RECEIVE MAP Request. You can use this in conversational applications to tell the WebSphere MQ application the structure of the ADS requested by the CICS application. The WebSphere MQ application can then build a RECEIVE MAP vector with this ADS, and send it as a new request.
As an application programmer, you can choose whether you want to interpret vector data in messages using the ADS, the ADSD, or the ADSDL. In order to interpret the ADS directly, you need to include the copybook from map assembly in your WebSphere MQ Bridge application. If you want to do this, but you do not have access to the copybook or map, you should recreate the map with the CICS utility DFHBMSUP - this requires CICS Transaction Server 1.2 or later.
If you want to interpret the ADS indirectly through the ADSD or ADSDL, for example if you are creating a generic application that will handle all maps, you do not need to include the copybook in your bridge application. Instead you need to send control information to the bridge that tells it to include the ADSD or ADSDL in outbound SEND MAP and RECEIVE MAP request vectors as required.
If your application must run in the distributed environment, you need to include an ADSDL in outbound SEND MAP vectors. WebSphere MQ can then perform data conversion on the outbound message.
You can specify any of the following options by setting appropriate values in field MQCIH.ADSDescriptor in inbound messages:
MQCIH.ADSDescriptor = MQCADSD_SEND
If you specify this alone, you will also get the short form of the ADS (application data structure) included in the SEND MAP vector.
MQCIH.ADSDescriptor = MQCADSD_RECV
The ADS is never present in an outbound RECEIVE MAP request vector.
MQCIH.ADSDescriptor = MQCADSD_MSGFORMAT
If you specify this, you will also get the long form of the ADS included in the SEND MAP vector.
MQCIH.ADSDescriptor = MQCADSD_NONE
This is the default. If you specify this, you will get the short form of the ADS included in the SEND MAP vector.
You can add MQCADSD_* values together, so do this to cause the long form of the application data structure descriptor to be included in both SEND MAP and RECEIVE MAP vectors:
MQCIH.ADSDescriptor = MQCADSD_SEND + MQCADSD_RECV + MQCADSD_MSGFORMAT
The SEND MAP vector would also in this case include an ADS in long form.
Your bridge application should contain logic to interpret outbound SEND MAP and RECEIVE MAP request vectors, and it should build and send an inbound RECEIVE MAP vector in response to the corresponding outbound RECEIVE MAP request.
An outbound SEND MAP vector can contain an application data structure (ADS) and an application data structure descriptor in short form (ADSD) or long form (ADSDL).
To interpret a SEND MAP vector, do this (assuming that the message contains both an ADS and an ADSD or ADSDL):
/* #includes */ #include cmqc.h /* WebSphere MQ header */ #include dfhbrmqh.h /* Vector structures */
·
·
·
/* #defines */
·
·
·
MQCHAR * MsgBuffer ; /* Message buffer pointer */ brmq_send_map * pVector ; /* Vector pointer */
·
·
·
/* Get message from reply queue */
·
·
·
/* Set the vector pointer to the start of the vector */ pVector = MsgBuffer + ((MQCIH *) MsgBuffer)->StrucLength ;
This diagram shows the structure of an outbound SEND MAP vector (assuming that you have set a pointer called pVector to address the start of the brmq_send_map vector, as in the code fragment above).
|---------------------------x'vvvvvvvv'------------------------->|
|---------------------x'zzzzzzzz'------------------->|
|----------------x'xxxxxxxx'------------>|
|---------sizeof(brmq_send_map)--------->|
--> x'wwwwwwww' <--
1804 O --> x'yyyyyyyy' <--
-------------- ... ------------------------...---------...----
|vvvv|FFFF|D444| |wwww|xxxx|yyyy|zzzz| ADS | ADSD or |
|vvvv|1804|6000| |wwww|xxxx|yyyy|zzzz| | ADSDL |
-------------- ... ------------------------...---------...----
^ ^ ^ ^ ^
pVector | | | pVector->brmq_sm_adsd_offset
| | pVector->brmq_sm_adsd_len
| pVector->brmq_sm_data_offset
pVector->brmq_sm_data_len
Values in the diagram shown like this:
ABCD 1234
show hexadecimal values as you would see them in an ISPF editor with 'hex on'. This is equivalent to the hexadecimal value x'A1B2C3D4'.
Fields pVector->brmq_sm_data_offset and pVector->brmq_sm_data_len give the offset and length, respectively, of the ADS, and fields pVector->brmq_sm_adsd_offset and pVector->brmq_sm_adsd_len give the offset and length, respectively, of the ADSD or ADSDL.
Fields brmq_sm_adsd_offset and brmq_sm_adsd_len will both be set to zero if no ADSD or ADSDL is included in the message.
The ADSD and ADSDL are both mapped to structures that are defined in header file dfhbrarh.h, which is distributed in library <hlq>.SDFHC370 for CICS Transaction Server for OS/390(R) Version 1.2 or later. You can examine the structure definitions there to see how the fields are laid out. The fields of the ADSD are also described in the CICS Internet and External Interfaces Guide for CICS V1.2, or the CICS External Interfaces Guide for CICS V1.3..
If your bridge application is to be compiled on a workstation, you will need to copy file dfhbrarh.h to that environment.
Both the ADSD and the ADSDL are represented by two types of structure. The first structure is the descriptor, which occurs only once at the start of the ADSD or ADSDL. These types are defined:
The second structure is the field descriptor, which is repeated once for each field in the map. These types are defined:
This can be shown diagrammatically like this for the ADSDL and the ADSD:
The ADSDL:
------------------------------------------------------ ... | ADS Descriptor | field descriptor | field descriptor | ------------------------------------------------------ ... ^ ^ ^ | | ads_long_field_descriptor | ads_long_field_descriptor ads_long_descriptor
The ADSD:
------------------------------------------------------ ... | ADS Descriptor | field descriptor | field descriptor | ------------------------------------------------------ ... ^ ^ ^ | | ads_field_descriptor | ads_field_descriptor ads_descriptor
Fields adsd_field_count and adsdl_field_count in the descriptors identify the number of field descriptors in the ADSD and ADSDL.
You can use the following code fragment to set pointers to the start of the ADSD or ADSDL structures and process the field descriptors sequentially. It is assumed that pVector already addresses the start of the brmq_send_map vector, and that you have an MQCIH structure named mqcih that contains the CIH from the inbound message.
/* #includes */ #include cmqc.h /* WebSphere MQ header */ #include dfhbrmqh.h /* Vector structures */ #include dfhbrarh.h /* ADSD structures */
·
·
·
/* Ptr to ADSD descriptor */ ads_descriptor * pADSD_D ; /* Ptr to ADSDL descriptor */ ads_long_descriptor * pADSDL_D ; /* Ptr to ADSD field descriptor */ ads_field_descriptor * pADSD_FD ; /* Ptr to ADSDL field descriptor */ ads_long_field_descriptor * pADSDL_FD ;
·
·
·
/* Initialize the pointer to the ADSDL descriptor or the */ /* ADSD descriptor depending on mqcih.ADSDescriptor */ if (mqcih.ADSDescriptor && MQCADSD_MSGFORMAT) { pADSDL_D = pVector->brmq_sm_adsd_offset; /* Long form */ pADSDL_FD = pADSDL_D + sizeof(ads_long_descriptor) ;
·
·
·
/* Enter a loop where we process all field descriptors */ /* in the ADSDL sequentially */ do { /* Perform some processing */
·
·
·
pADSDL_FD += sizeof(ads_long_field_descriptor) ; } while (pADSDL_FD < pADSDL_D->adsdl_length ) ; } else /* Short form */ { pADSD_D = pVector->brmq_sm_adsd_offset; /* Short form */ pADSD_FD = pADSD_D + sizeof(ads_descriptor) ; /* Enter a loop where we process all field descriptors */ /* in the ADSD sequentially */ do { /* Perform some processing */
·
·
·
pADSD_FD += sizeof(ads_field_descriptor) ; } while (pADSD_FD < pADSD_D->adsd_length ) ; }
·
·
·
The ADS itself is mapped to a structure that is generated when you assemble your map. If you include a keyword=parameter value of DSECT=ADSDL in your mapset definition macro, you will get the long form of the ADS. The output from map assembly is a union of two structures: an input structure and an output structure. This example shows part of such a union (only the first field definition is shown for each structure, and the comments have been added following map assembly).
union
{
struct {
char dfhms1[12]; /* 12 reserved bytes */
int dfhms2; /* Offset to next field */
int tranidl; /* Data length of this field */
int tranidf; /* Flag or attribute value */
int dfhms3[7]; /* Extended attributes array */
char tranidi[4]; /* Data value of field */
...
} bmstmp1i; /* Input structure */
struct {
char dfhms56[12]; /* 12 reserved bytes */
int dfhms57; /* Offset to next field */
int dfhms58; /* Data length of this field */
int tranida; /* Flag or attribute value */
int tranidc; /* Extended attribute */
int tranidp; /* Extended attribute */
int tranidh; /* Extended attribute */
int tranidv; /* Extended attribute */
int tranidu; /* Extended attribute */
int tranidm; /* Extended attribute */
int tranidt; /* Extended attribute */
char tranido[4]; /* Data value of field */
...
} bmstmp1o; /* Output structure */
} bmstmp1; /* Union */
The two structures are functionally identical, except that the input structure includes the extended attribute values in a seven-element array, and the output structure provides individually named fields.
You can use the following code fragment to set pointers to the start of the ADS. The structure names shown in the example DSECT above are used for illustration. Two pointers are set, the first to address inbound data and the second to address outbound data. It is assumed that pVector already addresses the start of the brmq_send_map vector.
/* #includes */ #include cmqc.h /* WebSphere MQ header */ #include dfhbrmqh.h /* Vector structures */ #include dfhbrarh.h .. /* ADSD structures */ #include mydsect.h /* DSECT from map assembly */
·
·
·
bmstmp1i * pADSI ; /* Pointer to the inbound ADS */ bmstmp1o * pADSO ; /* Pointer to the outbound ADS */ bmstmp1i * pADSI_An ; /* Inbound ADS Anchor */ bmstmp1o * pADSO_An ; /* Outbound ADS Anchor */
·
·
·
/* We are dealing with an outbound vector, so we will */ /* initialize the outbound pointer to address the ADS */ pADSO = pVector->brmq_sm_adsd_offset ; /* Save initial value as anchor */ pADSO_An = pADSO ; /* Move to the start of the first field */ pADSO += pADSDL_FD->adsdl_field_offset ; /* Enter a loop where we process all fields in the ADS */ /* sequentially. It is assumed that the value of pADSDL_FD */ /* is being augmented to the next field descriptor in the */ /* ADSDL with every loop. A model for this is shown in a code*/ /* fragment above. Note that adsdl_field_offset contains */ /* the absolute offset of the field from the start of the */ /* ADS. */ do { /* Perform some processing */
·
·
·
/* Add offset of next field to ADS Anchor value */ /* to address the next field */ pADSO = pADSO_An + pADSDL_FD->adsdl_field_offset ; } while (pADSDL_FD < pADSDL_D->adsd_length ) ;
·
·
·
The general structures of the long and short forms of the ADS are given in the IBM Redbook CICS Transaction Server for OS/390 Version 1 Release 3: Web Support and 3270 Bridge.
A RECEIVE MAP request is a request for the client to provide a RECEIVE MAP on the next input message. Unlike a SEND MAP vector, an outbound RECEIVE MAP request vector never contains an ADS. It contains an ADSD or ADSDL that describes the ADS data that it requires in the next inbound RECEIVE MAP vector, provided that MQCADSD_RECV has been specified in MQCIH.ADSDescriptor. The RECEIVE MAP vector structure differs from that of the SEND MAP vector. The main difference is that there are no fields giving the offset and length of the ADS.
Do this to interpret a RECEIVE MAP vector (assuming that the message contains an ADSD or ADSDL):
/* #includes */ #include cmqc.h /* WebSphere MQ header */ #include dfhbrmqh.h /* Vector structures */
·
·
·
/* #defines */
·
·
·
MQCHAR * MsgBuffer ; /* Message buffer pointer */ brmq_receive_map_request * pVector ; /* Vector pointer */
·
·
·
/* Get message from reply queue */
·
·
·
/* Set the vector pointer to the start of the vector */ pVector = MsgBuffer + ((MQCIH *) MsgBuffer)->StrucLength ;
·
·
·
This following diagram shows the structure of an outbound RECEIVE MAP request vector (the diagram assumes that you have set a pointer called pVector to address the start of the brmq_receive_map_request vector, as in the code fragment above).
|--------x'vvvvvvvv'----------------->|
sizeof(brmq_receive_map_request)
|------------------------>|
1802 O --> x'wwwwwwww' <--
-------------- ... ----------------
|vvvv|FFFF|D444| |wwww| ADSD or |
|vvvv|1802|6000| |wwww| ADSDL |
-------------- ... ----------------
^ ^
pVector pVector->brmq_rmr_adsd_len
Values in the diagram shown like this:
ABCD 1234
show hexadecimal values as you would see them in an ISPF editor with 'hex on'. This is equivalent to the hexadecimal value x'A1B2C3D4'.
Field pVector->brmq_rmr_adsd_len gives the length of the ADSD or ADSDL. No offset is given since the ADSDL is appended directly to the brmq_receive_map_request vector.
The ADSD or ADSDL has exactly the same structure in the RECEIVE MAP vector as in the SEND MAP vector, so once you have identified its start address you can proceed as described for the SEND MAP vector.
·
·
·
if (mqcih.ADSDescriptor && MQCADSD_MSGFORMAT) { pADSDL_D = pVector + sizeof(brmq_receive_map_request) ;
·
·
·
} else /* Short form */ { pADSD_D = pVector + sizeof(brmq_receive_map_request) ;
·
·
·
}
·
·
·
An example showing parts of an ADSDL and an ADS is given here. For full details of all the fields, see the references already cited. Values in the diagrams shown like this:
ABCD 1234
show hexadecimal values as you would see them in an ISPF editor with "hex on". This is equivalent to the hexadecimal value x'A1B2C3D4'.
This diagram shows the start of the ADSDL (even though the eyecatcher shows ADSL):
...½ADSL...........±....CHO L .........*.......&$...TRANID
000BCCED0000000100040000CCD444444444D400000F000F000100054000EDCDCC44...
005814230001000B001900033860000000003000000F000E00080000A00039159400...
^ ^ ^ ^ ^
| adsdl_field_count | | adsdl_first_field
adsdl_length | adsdl_map_columns
adsdl_map_lines
The fields named in this example show the following:
The next diagram shows the ADSDL first field descriptor and part of the next field descriptor.
TRANID ................L ..TERMID
EDCDCC444444444444444444444444440000000000000000D400ECDDCC4444444444...
3915940000000000000000000000000000060000000C000430003594940000000000...
^ ^ ^ ^ ^
adsdl_field_name | | | adsdl_next_field
| | adsdl_field_data_len
| adsdl_field_offset
adsdl_field_name_len
The fields named in this example show the following:
The next diagram shows the start of the ADS, which is in long form. The values here relate directly to the sample ADSDL shown above and are for the field named as TRANID in adsdl_field_name.
....................................................BAAA............ 0000000000000002000000000000000000000000000000000000CCCC000200000000... 000000000000000C0000000000000000000000000000000000002111000C00000000... ^ ^ ^ ^ | Offset to next field | Start of next field 12 bytes reserved Value of field
The meanings of the values shown here are as follows:
In this case, the field information is an exact multiple of fullwords. If this were not the case, padding bytes would appear after the data value and before the next field to ensure that it started on a fullword boundary. The padding bytes would be included in the 'offset to next field' value.
A number of attribute and extended attribute values for the field, not identified here, appear between the fullword giving the offset to the next field and the field value itself.
An application that starts a transaction that will issue an EXEC CICS RETRIEVE ... QUEUE(data-area) to retrieve its start data would send a message to the bridge with a RETRIEVE vector structure, which is defined in C as brmq_retrieve. The structure contains a character field of length eight bytes in which the application program must specify the name of the temporary storage queue that contains the data to be retrieved. A message containing a RETRIEVE vector is always the first in an exchange representing a conversation or pseudoconversation.