WBCDC - Web Interface Converter parms

  
  Licensed Materials - Property of IBM
  
  5655-Y04
  
  (C) Copyright IBM Corp. 1996, 2015 All Rights Reserved.
  
  
  This copybook defines the parameter lists which
  are passed to the 2 functions
  (DECODE and ENCODE)
  of the user replaceable converter program.
  
  --------------------------------------------------------------------
  
  The top level definition for dfhcommarea.
  
  --------------------------------------------------------------------

  --
  
  The fields at the start of the converter
  commarea must be accessible
  independent of the converter function being called.
  These declarations provide a definition of the
  commarea in terms of these common fields.
  
  < Variable >
  Meaning
  
  < converter_parms >
  The high-level definition of the parameter area
  passed to the converter in the COMMAREA.
  
  < converter_eyecatcher >
  The eyecatcher used to determine that the converter COMMAREA
  is not corrupt. The value it takes varies depending on the
  converter function involved. The possible values are
  defined in the DFHWBUCx copybook.
  
  < converter_function >
  The value used to determine which converter function is
  involved on this call. Possible values are the constants
  DECODE, ENCODE.
  
  < converter_response >
  The fullword response value produced by a converter
  which has not been passed a valid converter_function
  value. The recommended response in this circumstance
  is URP_INVALID.
  
  < converter_reason >
  The fullword reason value returned by a converter which has
  not been passed a valid converter_function value.
  No reason values are architected for this error situation in
  the CICS Web Browser Interface. Users may define their own values.
  
  < converter_parmlist >
  The rest of the parameters. The structure of this data
  varies depending on which converter function is involved.
  
  --------------------------------------------------------------------

  --
  
  These declarations define the parameter list which
  is passed to the DECODE function of the user replaceable
  converter program. It is called by the server controller.
  
  The variables in the decode parameter list are as follows:
  
  < Variable >
  Meaning
  
  < decode_eyecatcher > (input)
  A character field to contain an eyecatcher to help with
  diagnostics and provide a sanity check for the Converter
  program if required. The
  Server Controller sets this to the value of constant
  DECODE_EYECATCHER_INIT before calling decode.
  
  < decode_version > (input)
  @LIC
  A single-character parameter-list version identifier.
  It will change whenever the layout of the parameter list changes.
  Possible values:
  Binary zero (X'00') -- pre-CICS/TS1.3 version parameter list
  Character zero (X'F0') -- CICS/TS1.3 version parameter list
  Character one (X'F1') -- CICS/TS4.1 version parameter list
  
  < decode_volatile > (input)
  A single-character code that indicates whether the data area
  pointed to by "decode_data_ptr" can be replaced or not:
  '0' -- The area cannot be replaced: it is part of another
  commarea.
  '1' -- The storage pointed to by "decode_data_ptr" can be freed
  and replaced by a different size workarea.
  
  < decode_function > (input)
  A halfword set to the constant value URP_DECODE .
  Set to indicate to the converter the function required.
  
  < decode_response > (output)
  The response value produced by decode.
  Possible values are:
  
  - URP_OK
  - URP_EXCEPTION
  - URP_INVALID
  - URP_DISASTER
  
  < decode_reason > (output)
  The reason for a response produced by decode.
  The architected values for EXCEPTION responses are:
  
  - URP_SECURITY_FAILURE
  
  Other values may be supplied and given user-defined meanings.
  
  < decode_client_address > (input)
  The IP address of the client (ipv4 only).
  
  < decode_client_address_string > (input)
  The IP address of the client in "ww.xx.yy.zz" format. (ipv4 only)
  
  < decode_data_ptr > (input / output)
  A pointer to the HTTP request sent by the client.
  
  < decode_method_ptr > (input)
  Pointer to the method specified on the HTTP request sent by the
  client.
  
  < decode_http_version_ptr > (input)
  Pointer to a string identifying the HTTP version supported by the
  client.
  
  < decode_http_resource_ptr > (input)
  Pointer to the CICS resource requested by the client. In HTTP
  protocol
  terminology, this is the "absolute path" information in the HTTP
  request. Because CICS does not have any concept of "paths" or
  the hierarchical file systems on which paths rely, we have elected
  to use a term more appropriate to CICS in our documentation.
  
  < decode_request_header_ptr > (input)
  Pointer to the first HTTP header in the HTTP request. There are
  usually multiple HTTP headers for each HTTP request. Each header
  is delimited by a CR+LF. The end of the header information is
  delimited by a null header (that is, an additional CR+LF following
  final HTTP header).
  
  < decode_user_data_ptr > (input)
  A pointer to any user data for this HTTP request.
  
  < decode_method_length > (input)
  Length of the method specified on the HTTP request sent by the
  client.
  
  < decode_http_version_length > (input)
  Length of the string identifying the
  version of HTTP supported by the client.
  
  < decode_http_resource_length > (input)
  Length of the string containing the
  HTTP header information for this HTTP request.
  This length includes the lengths of all the delimiting CR+LFs
  for all the headers, including the final CR+LF of the null header
  which signals the end of the headers.
  
  < decode_request_header_length > (input)
  Length of the string identifying the
  CICS resource requested by supported by the client.
  
  < decode_user_data_length > (input)
  Length of the user data.
  
  < decode_input_data_len > (output)
  The server input data length associated
  with the program processing the HTTP request. This is set to the
  default 32767, but can be overwritten in decode,
  possibly to reflect information contained in the client data.
  This length is used as INPUTDATALENGTH on the EXEC CICS LINK to
  the user program.
  
  < decode_output_data_len > (output)
  The server output data length associated
  with the program processing the HTTP request. This is set to the
  default 32767, but can be overwritten in decode,
  possibly to reflect information contained in the client data. It
  is the size of the output commarea.
  
  < decode_server_program > (input / output)
  The CICS program invoked to process the incoming HTTP
  request. Initialised to the program name allocated by the ATTACH
  exit for the requested URL. The program name can be changed by
  the analyzer.
  
  < decode_user_token > (input / output)
  A token for use by users. Could for example identify
  any state data associated with this HTTP request.
  
  < decode_entry_count > (input)
  This parameter shows how many times the decode and encode
  converter functions have been executed in the current CWI
  execution. It is useful when looping back from encode.
  
  < decode_client_ipv6_address > (input)
  @LIA
  The IP address of the client. This field will contain either
  an ipv4 (in mapped format) or ipv6 client address.
  
  < decode_client_address_ipv6_string > (input)
  @LIA
  The IP address of the client in displayable format. If the client
  is ipv4 then a dotted decimal format will be storage here. And if
  the client is ipv6 then an IPV6 (colon formated) address will be
  supplied.
  
  --------------------------------------------------------------------

  --
  
  These declarations define the parameter list which
  is passed to the ENCODE function of the user replaceable
  Converter program. It is called by the alias program
  if data mapping of the remote procedure's output is required.
  The parameter list is passed as a commarea from the alias.
  
  < Variable >
  Meaning
  
  < encode_eyecatcher >
  A character field to contain an eyecatcher
  to help with diagnostics and provide a sanity check for
  the Converter program if required. The alias
  sets this to the value of constant ENCODE_EYECATCHER_INIT
  before calling encode.
  
  < encode_version > (input)
  A single-character parameter-list version identifier.
  It will change whenever the layout of the parameter list changes.
  Possible values:
  Binary zero (X'00') -- pre-CICS/TS1.3 version parameter list
  Character zero (X'F0') -- CICS/TS1.3 version parameter list
  
  < encode_volatile > (input)
  A single-character code that indicates whether the data area
  pointed to by "encode_data_ptr" can be replaced or not:
  '0' -- The area cannot be replaced: it is part of another
  commarea.
  '1' -- The storage pointed to by "encode_data_ptr" can be freed
  and replaced by a different size workarea.
  
  < encode_function > (input)
  A halfword set to the constant value URP_ENCODE .
  This is set by the alias before linking to the converter
  program. It allows the converter to determine which function
  is being requested.
  
  < encode_response > (output)
  The fullword response value produced by decode.
  Possible values are:
  
  - URP_OK
  - URP_EXCEPTION
  - URP_INVALID
  - URP_DISASTER
  
  < encode_reason > (output)
  The fullword reason value returned by encode for response
  values other than OK. No reason values are architected for
  encode in the CICS Web Browser Interface.
  Users may define their own values.
  
  < encode_data_ptr > (input)
  A pointer reference to the storage area containing
  the output from the server program which is to be manipulated
  by the encode function
  
  < encode_input_data_len > (input)
  A fullword field indicating the length of the data to be
  encoded by the converter.
  
  < encode_user_token > (input)
  A token for use by users. Could for example identify
  any state data associated with this HTTP request.
  < encode_entry_count > (input)
  This parameter shows how many times the decode and encode
  converter functions have been executed in the current CWI
  execution. It is useful when looping back from encode.
  
  --------------------------------------------------------------------