BRARC - BRXA definition

  
  Licensed Materials - Property of IBM
  
  5655-Y04
  
  (C) Copyright IBM Corp. 1996, 2008 All Rights Reserved.
  
  
  This is the description of the BRXA passed to the Bridge Exit as
  its COMMAREA.
  
  --------------------------------------------------------------------
  
  The BRXA header contains the following fields:
  
  BRXA_HEADER_EYECATCHER
  An eyecatcher to identify the area as an BRXA. This is
  initialised by CICS to the value BRXA_HEADER_EYE ('>BRAREA '),
  which is defined in the DFHBRACx copy book.
  BRXA_HEADER_LENGTH
  The length of the header.
  BRXA_HEADER_VERSION_NO
  The version number of the BRXA. This allows future releases to
  extend the BRXA. This is initialised by CICS to
  brxa_current_version_no.
  BRXA_TRANSACTION_AREA_PTR
  The address of the BRXA_TRANSACTION_AREA, which contains
  information relating to the Bridge Transaction and the User
  Transaction. This will be set by CICS, and should not be
  modified by the Bridge or LT Exit code.
  BRXA_TRANSACTION_AREA_LEN
  The length of the BRXA_TRANSACTION_AREA. This will be set by
  CICS, and should not be modified by the Bridge or LT Exit code.
  BRXA_COMMAND_AREA_PTR
  The address of the BRXA_COMMAND_AREA, which contains information
  relating to the command causing the Bridge Exit to be driven.
  This will be set by CICS, and should not be modified by the
  Bridge Exit code.
  BRXA_COMMAND_AREA_LEN
  The length of the BRXA_COMMAND_AREA. This will be set by CICS,
  and should not be modified by the Bridge or LT Exit code.
  BRXA_USER_AREA_PTR
  A user field which allows the address of a user area to be saved
  across Bridge Exit calls within a task. The user area should be
  obtains using an EXEC CICS GETMAIN.
  BRXA_USER_AREA_LEN
  A user fields which can be used to save the length of the user
  area. TRANSACTION.
  BRXA_INPUT_MSG_PTR
  A field used to save the address of an input message. This field
  is intended to be used in conjunction with a formatter.
  BRXA_INPUT_MSG_LEN
  A field used to save the current length of the input message.
  BRXA_OUTPUT_MSG_PTR
  A field used to save the address of an output message. This
  field is intended to be used in conjunction with a formatter.
  BRXA_OUTPUT_MSG_LEN
  A field used to save the current length of the output message.
  
  --------------------------------------------------------------------

        new for CTS 1.3

  --
  
  The BRXA transaction area contains information about the invoking
  Bridge transaction and the linked to transaction. This area is not
  meaningful when executing within the Bridge transaction and should
  not be referenced there. This information is completed by CICS for
  each invocation of the Bridge Exit. The transaction area contains
  the following information:
  
  BRXA_TRAN_AREA_EYECATCHER
  An eyecatcher to identify the area as an BRXA Transaction Area.
  This will be set by CICS, before passing control to the Bridge
  Exit, to the value BRXA_TRAN_AREA_EYE ('>BRTRANA'), which is
  defined in the DFHBRACx copy book.
  BRXA_BRIDGE_TRANID
  The transaction id of the Bridge Transaction.
  BRXA_TRANID
  The transaction id of the user transaction.
  BRXA_NEXTTRANID
  The transaction id of the next transaction.
  BRXA_ABEND_CODE
  If the User Transaction abends, then the abend code is placed
  here. If the transaction hasn't abended this field is blanks.
  BRXA_CALLING_PROG
  The name of the program in the User Transaction which issued the
  command causing the Bridge Exit to be invoked. For the
  BRXA_INIT, BRXA_BIND, BRXA_TERM and BRXA_ABEND calls this fields
  is set to blanks.
  BRXA_USERID
  specifies the userid under whose authority the Linked
  Transaction is to run.
  BRXA_STARTCODE
  specifies the type of method which would normally be used to
  start this transaction. This value is returned in the assign
  command, but has no other effect on processing. The following
  values are allowed:
  
  S
  START command without data
  SD
  START command with data
  TD
  Terminal Input (this is the default value)
  
  If an invalid value is specified the value TD is assumed.
  
  On invocation of the Bridge Exit for TERM and ABEND processing,
  this field contains the start code appropriate to the
  BRXA_NEXTTRANID value.
  BRXA_LOAD_ADS_DESCRIPTOR
  If this one character field is set to 'Y' by the Bridge
  Transaction, then for BMS SEND MAP and RECEIVE MAP, CICS will
  load the mapset and locate the ADS descriptor for the map, and
  the address of this descriptor will be passed to the LT exit in
  the command area. The format of this descriptor is defined in
  ADS_descriptor. If this field has any value other than 'Y', then
  CICS will not attempt to load the mapset and locate the
  descriptor, and brxa_ADS_descriptor_ptr will be set to null.
  BRXA_TRACE
  This field is set to 'Y' if level 2 tracing is set on for BR.
  The exit should use this flag to trace important information for
  diagnostic purposes. In particular the input and output data
  should be traced. Note that for BR level 2 tracing, the BRXA is
  already traced by CICS on input and output.
  BRXA_FACILITYLIKE
  The name of an installed 3270 terminal to be used as a template
  terminal definition for constructing the bridge facility.
  
  If a value is not specified CICS will look for a value specified
  as FACILITYLIKE in the user transaction's profile. If this value
  is also blanks, CICS will use the new CICS-supplied definition
  CBRF (based on model DFHLU2).
  
  If the specified FACILITYLIKE does not exist the Bridge CICS
  abends the transaction ABRJ.
  
  It is not possible to change the FACILITYLIKE definition after
  the terminal has been created, so this parameter is ignored if
  FACILITYTYPE is specified.
  
  If the template terminal definition is defined with QUERY(COLD)
  or QUERY(ALL) this will be ignored, and the predefined
  characteristics used.
  BRXA_FACILITY_KEEP_TIME
  This field specifies the time (in seconds) that the Bridge
  Facility will be kept after the User transaction terminates. If
  a non zero value is set in this field the Bridge Facility, and
  its pseudo conversational data will remain.
  
  This field is initially set to zero on the BRXA_INIT call. The
  exit only needs to set the value in the BRXA_TERM call.
  
  The maximum value is 1 week (604800 seconds). If a value larger
  than this is specified, CICS will keep the Bridge Facility for 1
  week.
  BRXA_FACILITYTYPE
  A token representing the Bridge Facility to be used. This value
  can be set on the BRXA_INIT call.
  
  Specifying a value implies reusing a Bridge Facility kept when a
  previous Bridge ran a user transaction, and kept the terminal.
  
  The default value of nulls will result in CICS dynamically
  allocating a new Bridge Facility.
  
  The name of the Bridge facility used is accessible to the user
  transaction in the EIBTRMID field of the EIB. No other TERMID's
  in the system will be the same, although the name may be re-used
  almost immediately when the user transaction finishes.
  BRXA_SCREEN_HEIGHT
  The current screen height
  BRXA_SCREEN_WIDTH
  The current screen width
  BRXA_ALTERNATE_SCREEN_HEIGHT
  The alternate screen height
  BRXA_ALTERNATE-SCREEN_WIDTH
  The alternate screen width
  BRXA_IDENTIFIER
  a 48 character field which can be used by the exit routine to
  associate the request with the specific use of the exit (for
  example, the MQ correlator for the MQ bridge, and the TCP/IP id
  for the Web).
  BRXA_FORMATTER
  An 8 byte character field to be used by the exit routine to
  specify the name of a formatter. If a value is specified in this
  field, then the formatter is called for BMS, TC, and IC
  requests. The bridge exit is only called for XM, SYNC and MSG
  requests.
  BRXA_CALL_EXIT_FOR_SYNC
  Should the bridge exit be called for syncpoint.
  BRXA_NEXTTRANID_SOURCE
  How was the next transid created?
  
  BRXA_IMMEDIATEBy a RETURN TRANSID IMMEDIATE command
  BRXA_STARTED By a START TRANSID command
  BRXA_NORMAL By a RETURN TRANSID or SET NEXTTRANSID command
  
  BRXA_TCTUA (PTR/LEN)
  Bridge facility's TCTUA
  BRXA_BRDATA_PTR
  Address of the data specified by the BRDATA parameter on the
  START TRANSID BREXIT command.
  BRXA_BRDATA_LEN
  Length of the BRDATA, as given on the START TRANSID BREXIT
  command.
  
  --------------------------------------------------------------------

        new for CTS 1.3

  --
  
  The command area contains information relating to the command
  which has caused the Bridge Exit to be called.
  
  Some fields are common for all commands, and there are some fields
  for specific commands.
  
  --------------------------------------------------------------------
  
  The common fields of the command area are:
  
  BRXA_COMMAND_AREA_EYECATCHER
  An eyecatcher to identify the area as an LT Command Area. This
  will be set by CICS, before passing control to the Bridge Exit,
  to the value BRXA_COMMAND_AREA_EYE ('>BRCOMMA'), which is
  defined in the DFHBRACx copy book.
  BRXA_FUNCTION_CODE
  A two character code identifying the CICS function for which the
  Bridge Exit is called. For calls for Initialise Transaction,
  Terminate Transaction and Abend Transaction this is 'XM'. For
  all other requests, this is the value in the first byte of EIBFN
  converted to character form. Valid EBCDIC characters are used
  for the function and command code to simplify testing of the
  values in User Transaction Exit programs written in all the
  supported languages, and to simplify passing of the codes to
  other systems. Constants with meaningful names are provided for
  all the supported languages to simplify testing,
  BRXA_COMMAND_CODE
  A two character code identifying the CICS command for which the
  Bridge Exit is called. For Initialise Transaction this is 'IN',
  for Terminate Transaction this is 'TM' and, for Abend
  Transaction this is 'AB'. For all other requests, this is the
  value in the second byte of EIBFN converted to character form.
  Valid EBCDIC characters are used for the function and command
  code to simplify testing of the values in User Transaction Exit
  programs written in all the supported languages, and to simplify
  passing of the codes to other systems. Constants with meaningful
  names are provided for all the supported languages to simplify
  testing,
  BRXA_USER_ABEND_CODE
  If this field is set to a non blank value (the default), CICS
  will generate a transaction abend with this code.
  
  Note that if the exit issues an EXEC CICS ABEND requests, this
  will result in a CICS DUMP, and will disable the exit.
  BRXA_FROM_PTR
  The address of the FROM data in SEND, CONVERSE, SEND MAP, SEND
  TEXT and START commands. This will be zero for other commands,
  or if FROM not specified on the command.
  BRXA_FROM_LEN
  The length of the FROM data in SEND, CONVERSE, SEND MAP, SEND
  TEXT and START commands. This will be zero for other commands,
  or if FROM not specified on the command. The length is a
  fullword,
  BRXA_INTO_PTR
  The address of the INTO data in RECEIVE, CONVERSE, RECEIVE MAP
  and RETRIEVE commads. This must be set by the User Transaction
  Exit, and CICS will copy data from this address into the INTO
  area specified on the command, or will copy the address into the
  SET parameter specified on the command.
  BRXA_INTO_LEN
  The length of the INTO data in RECEIVE, CONVERSE, RECEIVE MAP
  and RETRIEVE commads. This must be set by the User Transaction
  Exit, and CICS will copy this value into LENGTH, FLENGTH or
  INTOLENGTH parameter specified on the command, and use the value
  when copying data into the INTO area. The length is a fullword,
  
  NOTE: CONVERSE is the only command which has both FROM and INTO,
  and the BRXA_FROM_PTR and BRXA_INTO_PTR (and corresponding
  lengths) could be replaced by a single BRXA_DATA_PTR (and
  BRXA_DATA_LEN), and in the case of CONVERSE the exit would
  replace the FROM address and length by the INTO address and
  length,
  BRXA_RESP
  The resp code to be set (by CICS) in EIBRESP. This will be set
  to zero by CICS before calling the exit, and the exit must set
  this value if anything other than a normal response is required.
  
  CICS will generate an ABRN transaction abend if the value
  returned is not one that could normally be produced by CICS for
  this command. If this value is zero, CICS may itself set the
  EIBRESP value and raise a condition.
  BRXA_RESP2
  The resp code to be set (by CICS) in EIBRESP2. This will be set
  to zero by CICS before calling the exit, and the exit must set
  this value if anything other than a normal response is required.
  
  CICS does not check the value specified for consistency with the
  command. If this value is zero, CICS may itself set the EIBRESP
  value and raise a condition.
  BRXA_CPOSN
  The cursor position to be set (by CICS) in EIBCPOSN for RECEIVE,
  CONVERSE, RECEIVE MAP commands. This will be set to zero by CICS
  before calling the exit, and the exit must set this value, if
  the User Transaction uses the value in EIBCPOSN.
  BRXA_AID
  The attention id (PF key code) to be set (by CICS) in EIBAID for
  RECEIVE, CONVERSE, RECEIVE MAP commands. This will be set to
  ENTER (X'7D') by CICS before calling the exit, and the exit must
  set this value, if the User Transaction uses the value in
  EIBAID. The exit can use the values defined in DFHAID copy books
  to set the value (these are EBCDIC values of the 3270 AID
  characters).
  BRXA_ERASE_INDICATOR
  A one character value which is set (by CICS) to indicate whether
  ERASE, ERASE ALTERNATE or ERASE DEFAULT is specified on SEND,
  CONVERSE SEND MAP, SEND TEXT or SEND CONTROL commands. Constants
  with meaningful names are provided for all languages to allow
  the Bridge Exit to test this value if necessary.
  BRXA_LAST_INDICATOR
  a one character field indicating whether LAST specified on SEND
  command. Valid values are 'Y' or 'N', and constants are provided
  for the exit to test this field.
  BRXA_WAIT_INDICATOR
  a one character field indicating whether WAIT specified on SEND,
  RETRIEVE or ISSUE ERASEAUP. Valid values are 'Y' or 'N', and
  constants are provided for the exit to test this field.
  BRXA_FMT_RESPONSE
  This field is used by the formatter to tell the CICS that the
  bridge exit should be called to read or write a message.
  Possible values are:
  
  BRXA_FMT_NONE
  No action. The formatter has processed the request.
  BRXA_FMT_OUTPUT_BUFFER_FULL
  There is no room to add the next vector. Call the bridge exit
  to write the message, clear the buffer, then call the
  formatter again.
  BRXA_FMT_WRITE_MESSAGE
  The request required data to be flushed. Call the bridge exit
  to write the message.
  BRXA_FMT_REQUEST_NEXT_MESSAGE
  The formatter has run out of data in the message. Call the
  bridge exit to read a message, then call the formatter again.
  BRXA_FMT_READ_MESSAGE_NOWAIT
  The formatter has run out of data in the message. Check to see
  if there is a new message before requesting any further input.
  Call the bridge exit to read a message, then call the
  formatter again.
  
  BRXA_READ_NOWAIT_ISSUED
  This field is used by the formatter to check if it has already
  returned a brxa_fmt_read_message_nowait for this command.
  
  BRXA_NO
  A brxa_fmt_read_message_nowait has not been returned for this
  command.
  BRXA_YES
  A brxa_fmt_read_message_nowait has been returned for this
  command.
  
  BRXA_REQUEST_NEXT_ISSUED
  This field is used by the formatter to check if it has already
  returned a brxa_fmt_request_next_message for this command.
  
  BRXA_NO
  A brxa_fmt_request_next_message has not been returned for this
  command.
  BRXA_YES
  A brxa_fmt_request_next_message has been returned for this
  command.
  
  --------------------------------------------------------------------

        new for CTS 1.3

  --
  
  This command area defines actions at the initialisation and
  termination of the bridge. There are four functions:
  
  Init
  The purpose of this call is for the Bridge Exit pass CICS
  various parameters to run the transaction. Typically the BRDATA
  will be used to obtain this information.
  
  The following values can be set in the transaction and common
  areas area for this request.
  
  - BRXA_STARTCODE
  
  - BRXA_LOAD_ADS_DESCRIPTOR
  
  - BRXA_FACILITYLIKE
  
  - BRXA_FACILITY_TOKEN
  
  - BRXA_USER_ABEND_CODE
  
  - BRXA_IDENTIFIER
  
  - BRXA_FORMATTER
  
  Requests using recoverable resources can not be made in this
  call.
  Bind
  The purpose of this call is for the Bridge Exit to obtain data
  to answer 3270 requests in subsequent calls.
  
  Recoverable requests can be made in this call.
  
  The exit must not use the TWA, as this is not setup for the
  Bridge.
  
  The following values can be set in the transaction and common
  areas area for this request.
  
  - BRXA_STARTCODE
  
  - BRXA_LOAD_ADS_DESCRIPTOR
  
  - BRXA_FACILITY_KEEP_TIME
  
  - BRXA_USER_ABEND_CODE
  
  - BRXA_IDENTIFIER
  
  Term
  The purpose of this call is to inform the Bridge Exit that the
  user transaction is terminating. It also identifies the next
  transaction if this has been specified by the user transaction.
  
  This call is not made if the user transaction abends.
  
  Recoverable requests can be made in this call.
  
  The following values can be set in the transaction and common
  areas area for this request.
  
  - BRXA_FACILITY_KEEP_TIME
  
  - BRXA_USER_ABEND_CODE
  
  Abend
  In the event of the user transaction abending this call allows
  the Bridge Exit to issue non recoverable requests to the
  external resource, for example a non-syncpointing MQPUT can be
  issued for the MQ Bridge.
  
  The call can also change the abend code.
  
  Recoverable requests can not be made in this call.
  
  The following values can be set in the transaction and common
  areas area for this request Any other values are ignored.
  
  - BRXA_FACILITY_KEEP_TIME
  
  - BRXA_USER_ABEND_CODE
  
  --------------------------------------------------------------------

  --
  
  The Terminal Control command interface overlays the common command
  interface, and defines some Terminal Control specific parameters.
  
  Commands supported are SEND, RECEIVE and CONVERSE.
  
  The terminal control specific parameters are
  
  BRXA_CTLCHAR
  The 3270 Write Control Character (WCC) passed on SEND and
  CONVERSE commands as CTLCHAR. If not specified on the command
  the default value (X'C3'- unlock keyboard, reset MDT flags) is
  passed to the exit.
  BRXA_BUFFER_INDICATOR
  a one character field indicating whether BUFFER specified on
  RECEIVE command. Valid values are 'Y' or 'N', and constants are
  provided for the exit to test this field.
  
  (BUFFER is not allowed on CONVERSE - diagnosed by translator)
  BRXA_STRFIELD_INDICATOR
  a one character field indicating whether STRFIELD specified on
  SEND or CONVERSE command. Valid values are 'Y' or 'N', and
  constants are provided for the exit to test this field.
  BRXA_DEFRESP_INDICATOR
  a one character field indicating whether DEFRESP specified on
  SEND or CONVERSE command. Valid values are 'Y' or 'N', and
  constants are provided for the exit to test this field.
  BRXA_INVITE_INDICATOR
  a one character field indicating whether INVITE specified on
  SEND command. Valid values are 'Y' or 'N', and constants are
  provided for the exit to test this field.
  
  --------------------------------------------------------------------

  --
  
  The BMS command interface overlays the common command interface,
  and defines some BMS specific parameters.
  
  Commands supported are SEND MAP, SEND TEXT, SEND CONTROL and
  RECEIVE MAP.
  
  The BMS specific parameters are:
  
  BRXA_MAPSET
  The (unsuffixed) mapset name specified on SEND MAP or RECEIVE
  MAP.
  BRXA_MAP
  The map name specified on SEND MAP or RECEIVE MAP.
  BRXA_ADS_DESCRIPTOR_PTR
  The address of the ADS descriptor for BMS SEND MAP and RECEIVE
  MAP commands. This will be set by the interface code, if the
  Bridge has set the flag in the BRXA indicating that the
  descriptor should be loaded, and if the relevant mapset has been
  regenerated to include the descriptor. Otherwise this pointer
  will be set to 0.
  BRXA_CURSOR
  A halfword value containing the CURSOR position specified on
  SEND MAP, SEND TEXT or SEND CONTROL command, which identifies
  where the cursor is to be positioned on the 3270 screen. A value
  of -1 is passed if the application specified CURSOR with no
  value on SEND MAP command, indicating that symbolic cursor
  positioning is required, that is, that the cursor is to be
  positioned in the first field in the application data structure
  that has a value of -1 in the corresponding length field. A
  value of -2 is passed if the application did not specify CURSOR
  on the SEND MAP command.
  BRXA_MSR_DATA
  The four character value specified in MSR on SEND MAP, SEND
  CONTROL or SEND TEXT command. Constants are provided in the copy
  book DFHMSRCA which will allow the exit to test the values
  specified.
  
  NOTE: If we can assume that a BFB will always be constructed as
  if its TYPETERM was defined with MSRCONTROL(NO), then this
  parameter could be omitted, as for a 3270 terminal fro which
  MSRCONTROL(NO) is specified, BMS ignores the MSR field specified
  on the command.
  BRXA_DATA_INDICATOR
  a one character field indicating whether DATAONLY, MAPONLY or
  neither are specified on the SEND MAP command. Valid values are
  'D' (DATAONLY), 'M' (MAPONLY) or 'N'(neither specified) and
  constants are provided for the exit to test this field. (Note
  that if MAPONLY is specified, the FROM pointer and length will
  be zero, as there is no Apllication Data Structure in this
  case.)
  BRXA_ERASEAUP_INDICATOR
  a one character field indicating whether ERASAUP is specified on
  a SEND MAP or SEND CONTROL command. Valid values are 'Y' or 'N',
  and constants are provided for the exit to test this field.
  BRXA_FREEKB_INDICATOR
  a one character field indicating whether FREEKB is specified on
  a SEND MAP SEND TEXT or SEND CONTROL command. Valid values are
  'Y' or 'N', and constants are provided for the exit to test this
  field.
  BRXA_ALARM_INDICATOR
  a one character field indicating whether ALARM is specified on a
  SEND MAP, SEND TEXT or SEND CONTROL command. Valid values are
  'Y' or 'N', and constants are provided for the exit to test this
  field.
  BRXA_MSR_INDICATOR
  a one character field indicating whether MSR is specified on a
  SEND MAP , SEND TEXT or SEND CONTROL command. Valid values are
  'Y' or 'N', and constants are provided for the exit to test this
  field.
  BRXA_FRSET_INDICATOR
  a one character field indicating whether FRSET is specified on a
  SEND MAP or SEND CONTROL command. Valid values are 'Y' or 'N',
  and constants are provided for the exit to test this field.
  BRXA_TEXT_TYPE
  a one character field indicating whether NOEDIT or MAPPED is
  specified on a SEND TEXT command. Valid values are ' ' ( neither
  NOEDIT nor MAPPED specified), 'N' (NOEDIT specified) and 'M'
  (MAPPED specified) and constants are provided for the exit to
  test this field.
  
  --------------------------------------------------------------------

  --
  
  The Interval Control command interface overlays the common command
  interface, and defines some Interval Control specific parameters.
  
  The only command supported is RETRIEVE.
  
  The Interval Control specific parameters are:
  
  BRXA_RTERMID
  The value of RTERMID specified on START command. For the
  RETRIEVE command this is a field that the Bridge Exit can set to
  pass the RTERMID value back to the application issuing the
  RETRIEVE.
  BRXA_RTRANSID
  The value of RTRANSID specified on START command. For the
  RETRIEVE command this is a field that the Bridge Exit can set to
  pass the RTRANSID value back to the application issuing the
  RETRIEVE.
  BRXA_QUEUE
  The value of QUEUE specified on START command. For the RETRIEVE
  command this is a field in which the Bridge Exit can set the
  QUEUE value to be used by the application issuing the RETRIEVE.
  
  --------------------------------------------------------------------

  --
  
  This command area defines actions at syncpoint and syncpoint
  rollback. brxa_explicit is used to indicate whether this request
  originated from an explicit EXEC CICS SYNCPOINT command, or
  whether it is an implicit syncpoint generated by CICS. It will be
  set to 'Y' or 'N' prior to invoking the exit, and constants are
  provided for the exit to test this field. Valid values for
  rollback are 'Y' or 'N', and constants are provided for the exit
  to test this field.
  
  --------------------------------------------------------------------

  --
  
  This command area defines actions when the bridge exit is called
  to read or write a message. These functions are only used if the
  bridge exit specified a formatter on initialisation.
  
  This command area defines the following functions:
  
  Init
  The purpose of this call is for the Bridge Exit pass CICS
  various parameters to run the transaction. Typically the BRDATA
  will be used to obtain this information.
  
  The following values can be set in the transaction and common
  areas area for this request.
  
  - BRXA_STARTCODE
  
  - BRXA_LOAD_ADS_DESCRIPTOR
  
  - BRXA_FACILITYLIKE
  
  - BRXA_FACILITY_TOKEN
  
  - BRXA_USER_ABEND_CODE
  
  - BRXA_IDENTIFIER
  
  --------------------------------------------------------------------

  --
  
  The ADS descriptor is provided to allow interpretation of the BMS
  Application Data Structure - that is, the structure used by the
  application program for the data in SEND and RECEIVE MAP requests
  - by an exit program, without requiring the exit program to
  include the relevant copy book at compile time.
  
  The ADS descriptor is only available if the map load module has
  been reassembled to include the descriptor, and CICS only attempts
  to locate the descriptor if the brxa_load_ADS_descriptor indicator
  is set to brxa_yes in the Bridge Exit initialisation call.
  
  The ADS descriptor contains a header containing general
  information about the map, together with a field descriptor for
  every field which appears in the ADS, that is every named field in
  the map definition macro.
  
  The header consists of the following information
  
  ADSD_LENGTH
  The length of the ADS descriptor
  ADSD_EYECATCHER
  An eyecatcher ('ADSD') to identify this as an ADS descriptor
  ADSD_MAP_INDEX
  The index of the map within the mapset. This is needed to
  determine the HTML template corresponding to the map.
  ADSD_FIELD_COUNT
  the number of fields within the ADS, that is the number of named
  fields in the map definition macros. A separate field is counted
  for each element of an array defined with the OCCURS parameter,
  but subfields of group fields (GRPNAME) are not counted. The
  field count may be zero, in which case there are no field
  descriptors following the header.
  ADSD_STRUCTURE_LENGTH
  the length of the application data structure
  ADSD_ATTRIBUTE_NUMBER
  the number of extended attributes in each field of the ADS, that
  is the number of attributes specified in DSATTS in the map
  definition.
  ADSD_ATTRIBUTE_TYPE_CODES
  
  one character code for the attribute types in each field, in
  order, derived from DSATTS
  
  - C = COLOR
  
  - P = PS
  
  - H = HILIGHT
  
  - V = VALIDN
  
  - O = OUTLINE
  
  - S = SOSI
  
  - T = TRANSP
  
  ADSD_MAP_JUSTIFY_HOR
  the horizontal justification for the map, either L (LEFT) or R
  (RIGHT) from JUSTIFY operand on map definition.
  ADSD_MAP_JUSTIFY_VER
  the vertical justification for the map, from JUSTIFY operand on
  map definition. This can have the values F (FIRST), L (LAST) or
  B (BOTTOM) or blank (no vertical JUSTIFY operand).
  ADSD_MAP_STARTING_LINE
  the starting line for the map, from LINE operand on DFHMDI macro
  (LINE = NEXT will give a value of 255, LINE = SAME will give a
  value of 254)
  ADSD_MAP_STARTING_COLUMN
  the starting column for the map, from COLUMN operand on DFHMDI
  macro (COLUMN = NEXT will give a value of 255, COLUMN = SAME
  will give a value of 254)
  ADSD_MAP_LINES
  the number of lines in the map from SIZE= operand
  ADSD_MAP_COLUMNS
  the number of columns in the map from SIZE= operand
  ADSD_WRITE_CONTROL_CHAR
  the 3270 encoded WCC derived from CONTROL= operand
  ADSD_FIRST_FIELD
  the first field descriptor occurs here. Use the address of
  ADSD_FIRST_FIELD as the initial value of the pointer for the
  field descriptor (unless ADSD_field_count is 0).
  
  The field descriptor for each field within the map consists of
  
  ADSD_FIELD_NAME
  the unsuffixed field name padded with blanks
  ADSD_FIELD_NAME_LEN
  the number of characters in the field name
  ADSD_OCCURS_INDEX
  when OCCURS is specified for a field definition there will be a
  separate field descriptor for each element of the array, and
  occurs_index will indicate the array index for the particular
  field if OCCURS not specified, then occurs_index will be 0
  ADSD_FIELD_OFFSET
  the offset of the field within the ADS the offset is to the
  beginning of the (halfword) length field, and users must add 2
  (for the length field) + 1 (for the 3270 attribute) +
  attribute_number (for the extended attributes specified in
  DSATTS) to get the offset of the data part of the field
  ADSD_FIELD_DATA_LEN
  the length of the field in the ADS
  ADSD_FIELD_JUSTIFY
  indicates whether the data is to be justified left (L) or right
  (R) if the supplied length is less than the length in the ADS
  ADSD_FIELD_FILL_CHAR
  the character (blank or '0') to be used to fill the remainder of
  the field in the ADS.
  ADSD_NEXT_FIELD
  the next field descriptor occurs here. Use the address of
  ADSD_NEXT_FIELD to update the pointer for the field descriptor.
  
  --------------------------------------------------------------------

  --