home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / netds / sna / shared / cpicerrs.h < prev    next >
Text File  |  1997-04-09  |  22KB  |  528 lines
  1. /*****************************************************************************
  2.  *
  3.  *  MODULE NAME: CPICERRS.H
  4.  *
  5.  *  COPYRIGHTS:
  6.  *             This module contains code made available by IBM
  7.  *             Corporation on an AS IS basis.  Any one receiving the
  8.  *             module is considered to be licensed under IBM copyrights
  9.  *             to use the IBM-provided source code in any way he or she
  10.  *             deems fit, including copying it, compiling it, modifying
  11.  *             it, and redistributing it, with or without
  12.  *             modifications.  No license under any IBM patents or
  13.  *             patent applications is to be implied from this copyright
  14.  *             license.
  15.  *
  16.  *             A user of the module should understand that IBM cannot
  17.  *             provide technical support for the module and will not be
  18.  *             responsible for any consequences of use of the program.
  19.  *
  20.  *             Any notices, including this one, are not to be removed
  21.  *             from the module without the prior written consent of
  22.  *             IBM.
  23.  *
  24.  *  AUTHOR:    Peter J. Schwaller
  25.  *             VNET:     PJS at RALVM6           Tie Line: 444-4376
  26.  *             Internet: pjs@ralvm6.vnet.ibm.com     (919) 254-4376
  27.  *
  28.  *             John Q. Walker
  29.  *             VNET:     JOHNQ at RALVM6         Tie Line: 444-4414
  30.  *             Internet: johnq@ralvm6.vnet.ibm.com   (919) 254-4414
  31.  *
  32.  *  AVAILABILITY:
  33.  *             These sample programs and source are also available on
  34.  *             CompuServe through the APPC Information Exchange.  To get
  35.  *             to the APPC forum just type 'GO APPC' from any CompuServe
  36.  *             prompt.  The samples are available in the Sample Programs
  37.  *             library section.  Just search on the keyword CPICPGMS to
  38.  *             find all the samples in this series.
  39.  *
  40.  *             Updates for the sample programs and support for many more
  41.  *             CPI-C platforms will also be made available on CompuServe.
  42.  *
  43.  *  RELATED FILES:
  44.  *             Use CPICERR.C
  45.  *
  46.  *  CHANGE HISTORY:
  47.  *  Date       Description
  48.  *  08/05/92   Version 2.31 of APING, ATELL and AREXEC released to CompuServe.
  49.  *             This version was also distributed at the APPC/APPN Platform
  50.  *             Developer's Conference held in Raleigh, NC.
  51.  *  08/13/92   Changed cpicerr_handle_rc() to a macro referencing
  52.  *             cpicerr_handle_rc_extended().  The macro adds the current
  53.  *             source file and line number to improve source code debugging.
  54.  *  11/04/92   Changed version from char to unsigned char.
  55.  *  11/15/92   Changed reply structure to include 2 byte indicator.
  56.  *  11/17/92   Added send/receipt of operating system string.
  57.  *             Added cpicerr_exchange_version_plus() to return the string.
  58.  *
  59.  *****************************************************************************/
  60.  
  61. /*****************************************************************************
  62.  *
  63.  * OVERVIEW OF CPICERR CALLS
  64.  *
  65.  * cpicerr_new()                      Creates a CPICERR object.
  66.  *                                    This must be done before any other
  67.  *                                    cpicerr calls can be used.
  68.  *
  69.  * These calls set values in the cpicerr object structure and affect how
  70.  * cpicerr_handle_rc reacts to errors.
  71.  *
  72.  * cpicerr_set_log_file_name()        What filename to use for logging
  73.  * cpicerr_set_log_file_path()        Where the filename is
  74.  * cpicerr_set_program_name()         String - Output as part of log info
  75.  * cpicerr_set_program_info()         String - Output as part of log info
  76.  * cpicerr_set_major_version()        8 bit int - see cpicerr_exchange_version
  77.  * cpicerr_set_minor_version()        8 bit int - see cpicerr_exchange_version
  78.  * cpicerr_set_conv_id()              Used to extract conversation state info
  79.  * cpicerr_set_exit_level()           Level of error on which to exit
  80.  * cpicerr_set_show_level()           Level of error on which to show errors
  81.  * cpicerr_set_log_level()            Level of error on which to log errors
  82.  *
  83.  * cpicerr_handle_rc()                Should be called by the program for all
  84.  *                                    UNEXPECTED return codes.
  85.  *                                    Functions performed are:
  86.  *                                       Classification of the return code
  87.  *                                       Showing partial info to end user
  88.  *                                       Logging complete info to disk
  89.  *                                    This is a macro that actually expands
  90.  *                                    to cpicerr_handle_rc_extended().
  91.  *
  92.  * cpicerr_destroy()                  Destroys the CPICERR  object.
  93.  *
  94.  *
  95.  * cpicerr_classify_rc()              These are internal calls used by
  96.  * cpicerr_show_rc()                  other cpicerr_handle_rc.
  97.  * cpicerr_log_cpicerr()
  98.  * cpicerr_get_message()
  99.  * cpicerr_set_rc_info()
  100.  * cpicerr_show_product_info()
  101.  *
  102.  *****************************************************************************/
  103.  
  104. #ifndef INCL_CPICERR
  105. #define INCL_CPICERR
  106.  
  107.  
  108. /*
  109.  * Include the C standard I/O library for the FILE structure definition.
  110.  */
  111. #include <stdio.h>
  112.  
  113. /*
  114.  * Collection of routines with special ported version for each platform
  115.  * The only thing that is used from CPICDEFS.H is the correct setting
  116.  * of the SHORT_IDENTIFIERS identifier.
  117.  */
  118. #include "cpicdefs.h"
  119.  
  120. #if defined(SHORT_IDENTIFIERS)
  121. /*
  122.  * The C/370 compiler requires that identifier be unique in the 1st 8 chars.
  123.  * If any new functions are added to this file, they should also be added to
  124.  * this list, with a unique mapping.
  125.  */
  126. #    define  cpicerr_build_reply_image      cebri
  127. #    define  cpicerr_conv_types             ceconv_type
  128. #    define  cpicerr_classify_rc            cecr
  129. #    define  cpicerr_create_reply           cecrep
  130. #    define  cpicerr_destroy                cedestroy
  131. #    define  cpicerr_destroy_reply          cedr
  132. #    define  cpicerr_extract_reply_image    ceeri
  133. #    define  cpicerr_exchange_version       ceev
  134. #    define  cpicerr_exchange_version_plus  ceevp
  135. #    define  cpicerr_get_message            cegm
  136. #    define  cpicerr_handle_rc_extended     cehre
  137. #    define  cpicerr_log_cpicerr            celf
  138. #    define  cpicerr_set_major_version      cemajor
  139. #    define  cpicerr_set_minor_version      ceminor
  140. #    define  cpicerr_new                    cenew
  141. #    define  cpicerr_recv_appl_error        cerae
  142. #    define  cpicerr_return_codes           cerc
  143. #    define  cpicerr_rc_classes             cercclass
  144. #    define  cpicerr_send_appl_error        cesae
  145. #    define  cpicerr_set_conv_id            cesci
  146. #    define  cpicerr_set_error_reply        ceser
  147. #    define  cpicerr_set_rc_info            cesetr
  148. #    define  cpicerr_set_log_file_name      ceslfn
  149. #    define  cpicerr_set_log_file_path      ceslfp
  150. #    define  cpicerr_set_log_level          cesll
  151. #    define  cpicerr_set_program_info       cespi
  152. #    define  cpicerr_set_program_name       cespn
  153. #    define  cpicerr_show_product_info      cespri
  154. #    define  cpicerr_show_rc                cesr
  155. #    define  cpicerr_show_reply             cesrep
  156. #    define  cpicerr_set_show_level         cessl
  157. #    define  cpicerr_states_conv            cestate
  158. #    define  cpicerr_set_exit_level         cesxl
  159. #    define  cpicerr_sync_levels            cesync
  160. #    define  cpicerr_verbs_long             cvlong
  161. #    define  cpicerr_verbs_short            cvshort
  162. #endif
  163.  
  164. /* Needed for the time_t structure used within the CPICINIT structure */
  165. #include <time.h>
  166.  
  167. /*
  168.  * Specify the maximum sizes for a variety of CPI-C fields.
  169.  * The +1 is added to allow room for the C null terminator for strings.
  170.  */
  171. #define  MAX_LU_ALIAS      (8+1)
  172. #define  MAX_PLU_ALIAS     (8+1)
  173. #define  MAX_TP_NAME       (64+1)
  174. #define  MAX_SYM_DEST_NAME (8+1)
  175. #define  MAX_FQPLU_NAME    (17+1)
  176. #define  MAX_DESTINATION   (17+1)
  177. #define  MAX_MODE_NAME     (8+1)
  178. #define  MAX_USERID        (8+1)
  179. #define  MAX_PASSWORD      (8+1)
  180.  
  181.  
  182.  
  183. #define  MAX_MESSAGE_TEXT_LENGTH    (2048)
  184.  
  185.  
  186. /*****************************************************************************
  187.  * These values are used to break the CPI-C return codes down into classes.
  188.  * They are organized from errors that can be ignored, to fatal errors
  189.  * which cannot be recovered from.
  190.  *
  191.  * The values ALL_ERRORS and NO_ERRORS are used as extremes for the
  192.  * cpicerr_set_exit_level() and cpicerr_set_show_level() calls, and are
  193.  * not actual classification values.
  194.  *****************************************************************************/
  195. typedef enum {
  196.     RC_OK = 0,
  197.     ALL_ERRORS,
  198.     CONTINUE          ,
  199.     RETRY_VERB        ,
  200.     SECURITY_NOT_VALID,
  201.     ERROR_RECEIVED    ,
  202.     RETRY_CONV        ,
  203.     RETRY_CONV_BO     ,
  204.     BACKOUT_RECEIVED  ,
  205.     UNRECOVERABLE     ,
  206.     UNRECOVERABLE_BO  ,
  207.     NO_ERRORS
  208. } CPIC_RC_HANDLING;
  209.  
  210. /*
  211.  * Since CPI-C does not provide actual values that correspond to each CPI-C
  212.  * call, we have to invent our own so that we can put the call names into
  213.  * our message lists.
  214.  */
  215. typedef enum {
  216.     MSG_CMACCP,
  217.     MSG_CMALLC,
  218.     MSG_CMCFM ,
  219.     MSG_CMCFMD,
  220.     MSG_CMDEAL,
  221.     MSG_CMECS ,
  222.     MSG_CMECT ,
  223.     MSG_CMEMN ,
  224.     MSG_CMEPLN,
  225.     MSG_CMESL ,
  226.     MSG_CMFLUS,
  227.     MSG_CMINIT,
  228.     MSG_CMPTR ,
  229.     MSG_CMRCV ,
  230.     MSG_CMRTS ,
  231.     MSG_CMSCT ,
  232.     MSG_CMSDT ,
  233.     MSG_CMSED ,
  234.     MSG_CMSEND,
  235.     MSG_CMSERR,
  236.     MSG_CMSF  ,
  237.     MSG_CMSLD ,
  238.     MSG_CMSMN ,
  239.     MSG_CMSPLN,
  240.     MSG_CMSPTR,
  241.     MSG_CMSRC ,
  242.     MSG_CMSRT ,
  243.     MSG_CMSSL ,
  244.     MSG_CMSST ,
  245.     MSG_CMSTPN,
  246.     MSG_CMTRTS,
  247.     MSG_XCSCSU,
  248.     MSG_XCSCST,
  249.     MSG_XCSCSP,
  250.     MSG_XCECST,
  251.     MSG_XCECSU,
  252.     MSG_XCMSSI,
  253.     MSG_XCMESI,
  254.     MSG_XCMDSI
  255. } CPIC_VERB_INDEX;
  256.  
  257.  
  258. /*****************************************************************************
  259.  *
  260.  * CPICERR_REPLY
  261.  *
  262.  * This structure is a reusable reply format.  This can be used either
  263.  * as part of a data reply, or as an error reply after a send_error()
  264.  * call.  See CPICERR.C for complete details of how this structure
  265.  * is formatted on a CPI-C conversation.
  266.  *****************************************************************************/
  267.  
  268. typedef enum next_state {
  269.     NEXT_SEND,
  270.     NEXT_RECEIVE,
  271.     NEXT_DEALLOCATE,
  272.     NEXT_DEALLOCATE_AND_EXIT
  273. } NEXT_STATE;
  274.  
  275. typedef enum reply_response {
  276.     REPLY_POSITIVE_COMPLETE     = 1,
  277.     REPLY_POSITIVE_INTERMEDIATE = 2,
  278.     REPLY_NEGATIVE_TRANSIENT    = 3,
  279.     REPLY_NEGATIVE_PERMANENT    = 4
  280. } REPLY_RESPONSE;
  281.  
  282. typedef struct cpicerr_reply {
  283.     unsigned short      length;
  284.     unsigned short      buffer_length;
  285.     char *              buffer;
  286. } CPICERR_REPLY;
  287.  
  288. /*
  289.  * The format of the reply buffer is:
  290.  * Offset   Length   Field
  291.  * ------   ------   -----
  292.  *    0        2     Reply Indicator (0xFF01)
  293.  *    2        1     response
  294.  *    3        1     reserved (must be 0)
  295.  *    4        2     message category
  296.  *    6        4     primary code
  297.  *   10        4     secondary code
  298.  * The following two fields are optional:
  299.  *   12        2     primary message length
  300.  *   14        x     primary message text
  301.  * The following two fields are optional and should follow the primary message:
  302.  *  14+x       2     secondary message length
  303.  *  16+x       y     secondary message text
  304.  */
  305.  
  306.  
  307. #define CPICERR_REPLY_INDICATOR_VALUE   (0xFF01)
  308. #define CPICERR_REPLY_MIN_LENGTH        (14)
  309.  
  310. /* offsets into the reply buffer for each field */
  311. #define CPICERR_REPLY_INDICATOR         (0)
  312. #define CPICERR_REPLY_RESPONSE          (2)
  313. #define CPICERR_REPLY_RESERVED          (3)
  314. #define CPICERR_REPLY_CATEGORY          (4)
  315. #define CPICERR_REPLY_PRIMARY           (6)
  316. #define CPICERR_REPLY_SECONDARY        (10)
  317. #define CPICERR_REPLY_PRIMARY_LENGTH   (14)
  318. #define CPICERR_REPLY_PRIMARY_TEXT     (16)
  319.  
  320. /*****************************************************************************
  321.  *
  322.  * CPICERR
  323.  *
  324.  * This structure contains all of the information necessary to for all
  325.  * cpicerr calls.  All of the fields which need to be changed by the
  326.  * application program should be modified through the cpicerr_set...()
  327.  * calls.  The application program should never have to access the
  328.  * cpicerr structure directly.
  329.  *
  330.  * When an unexpected return code occurs, this structure is used to
  331.  * determine what error processing should occur, including:
  332.  *   display of minimal error information
  333.  *   logging of complete error information
  334.  *     where to log the data
  335.  *
  336.  * If a field is added to this structure, be sure to add the correct
  337.  * initialization values for the field in the cpicerr_new() function.
  338.  *****************************************************************************/
  339.  
  340. typedef struct error_handler_cpicerr {
  341.     char *        program_name;             /* program's name                */
  342.     char *        program_info;             /* program information           */
  343.     CPIC_VERB_INDEX verb_index;             /* index of the failing verb     */
  344.     CM_RETURN_CODE conv_rc;                 /* return code from CPI-C        */
  345.     CM_CONVERSATION_STATE conversation_state;
  346.     CM_CONVERSATION_TYPE  conversation_type;
  347.     CM_SYNC_LEVEL         sync_level;
  348.     char *        log_file_path;            /* path for the log file         */
  349.     char *        log_file_name;            /* where to log errors           */
  350.     unsigned char conversation_id[8];       /* CPI-C Conversation ID         */
  351.     int           conv_id_set;              /* Was conv_id set?              */
  352.     CM_INT32      mode_name_length;         /* mode_name length              */
  353.     CM_INT32      partner_LU_name_length;   /* partner_LU_name length        */
  354.     unsigned char mode_name[MAX_MODE_NAME]; /* mode_name                     */
  355.     unsigned char partner_LU_name[MAX_FQPLU_NAME]; /* partner_LU_name        */
  356.     CPIC_RC_HANDLING exit_level;            /* should we exit on an error?   */
  357.     CPIC_RC_HANDLING show_level;            /* should we show errors?        */
  358.     CPIC_RC_HANDLING log_level;             /* should we log errors?         */
  359.     unsigned char major_version;            /* Major version number          */
  360.     unsigned char minor_version;            /* Minor version number          */
  361.     time_t        program_start_time;       /* time of cpicerr init          */
  362.     time_t        program_error_time;       /* time of error report          */
  363.     int           handle_error;             /* should cpicerr process all    */
  364.                                             /* ERROR_RECEIVED ret codes?     */
  365. } CPICERR;
  366.  
  367.  
  368. /*****************************************************************************
  369.  * The following are the structures and constants used for handling all of
  370.  * message strings in CPICERR.
  371.  *****************************************************************************/
  372.  
  373. /*
  374.  * The cpicerr_message structure contains an index and the text message
  375.  * associated with that index.  In most cases, the index will be an actual
  376.  * CPI-C return value.  For example,
  377.  * index = CM_SEND_STATE, message = "Send state"
  378.  */
  379. typedef struct cpicerr_message {
  380.     CM_INT32   index;
  381.     char *     message;
  382. } CPICERR_MESSAGE;
  383.  
  384.  
  385. /*
  386.  * This enum gives each list a label and a value to make it easier to
  387.  * process all of the lists.
  388.  */
  389. typedef enum cpicerr_message_type {
  390.     CPIC_SYNC_LEVELS  = 1,
  391.     CPIC_CONV_TYPES   = 2,
  392.     CPIC_STATES_CONV  = 3,
  393.     CPIC_RC_CLASSES   = 4,
  394.     CPIC_RETURN_CODES = 5,
  395.     CPIC_VERBS_SHORT  = 6,
  396.     CPIC_VERBS_LONG   = 7
  397. } CPICERR_MESSAGE_TYPE;
  398.  
  399. /*
  400.  * The CPICERR_MESSAGE_LIST structure is what actually ties a
  401.  * CPICERR_MESSAGE_TYPE value to the CPICERR_MESSAGE list that it relates
  402.  * to.  A table is defined in CPICERR.C that allows the cpicerr_get_message
  403.  * routine to correlate a message label to its corresponding message list.
  404.  */
  405. typedef struct cpicerr_message_list {
  406.     CPICERR_MESSAGE_TYPE type;
  407.     CPICERR_MESSAGE *    list;
  408. } CPICERR_MESSAGE_LIST;
  409.  
  410. /*
  411.  * The following value is used to mark the end of CPICERR_MESSAGE lists.
  412.  */
  413. #define  MAX_MESSAGE       32767
  414.  
  415.  
  416. /*
  417.  * Set the size of the buffer used by the cpicerr_exchange_version() call.
  418.  */
  419. #define  EXCHANGE_BUFFER_SIZE    128
  420.  
  421.  
  422. /*
  423.  * If these CPI-C calls are not supported, these values will be returned
  424.  * instead of a valid CPI-C values.  In the message tables, the values
  425.  * below will result in a message of "XXX not supported".  This allows
  426.  * us to differentiate between a call not being available on a platform,
  427.  * and an unrecognized value returned on a call.
  428.  */
  429. #define CMECS_NOT_SUPPORTED              (CM_CONVERSATION_STATE) 99
  430.  
  431.  
  432.  
  433. /*
  434.  * Used by the cpicerr_exchange_version() routine.  Future flows may
  435.  * be prefaced with new "command values" taken from this list.
  436.  */
  437. typedef enum cpicerr_command {
  438.     CPICERR_EXCHANGE_VERSION = 1,
  439.     CPICERR_EXCHANGE_OPSYS_STRING = 2
  440. } CPICERR_COMMAND;
  441.  
  442.  
  443. /*****************************************************************************
  444.  * Function prototypes for routines that can be called via an application
  445.  * program.  See CPICERR.C for a full description of each function and
  446.  * how to use it.
  447.  *****************************************************************************/
  448. CPICERR *
  449.        cpicerr_new(void);
  450.  
  451. void   cpicerr_show_reply(       CPICERR_REPLY * reply);
  452. CPICERR_REPLY *
  453.        cpicerr_create_reply(     unsigned int primary_message_buffer_size,
  454.                                  unsigned int secondary_message_buffer_size);
  455. void   cpicerr_destroy_reply(    CPICERR_REPLY * reply);
  456. unsigned int
  457.        cpicerr_build_reply_image(CPICERR_REPLY * reply,
  458.                                  char *          reply_buffer,
  459.                                  unsigned int    reply_buffer_length);
  460. unsigned int
  461.        cpicerr_extract_reply_image(CPICERR_REPLY * reply,
  462.                                  char *          reply_buffer,
  463.                                  unsigned int    reply_buffer_length);
  464. void   cpicerr_set_error_reply(  CPICERR_REPLY * reply,
  465.                                  REPLY_RESPONSE  response,
  466.                                  unsigned int    message_category,
  467.                                  unsigned long   primary_code,
  468.                                  char *          primary_message_text,
  469.                                  unsigned long   secondary_code,
  470.                                  char *          secondary_message_text);
  471. int    cpicerr_recv_appl_error(  CPICERR *  cpicerr,
  472.                                  CPICERR_REPLY * reply);
  473. int    cpicerr_send_appl_error(  CPICERR *  cpicerr,
  474.                                  NEXT_STATE next_state,
  475.                                  CPICERR_REPLY * reply);
  476. int    cpicerr_set_program_name( CPICERR *            cpicerr,
  477.                                  char *               program_name);
  478. int    cpicerr_set_program_info( CPICERR *            cpicerr,
  479.                                  char *               program_info);
  480. int    cpicerr_set_major_version(CPICERR *            cpicerr,
  481.                                  unsigned char        major_version);
  482. int    cpicerr_set_minor_version(CPICERR *            cpicerr,
  483.                                  unsigned char        minor_version);
  484. int    cpicerr_set_conv_id(      CPICERR *            cpicerr,
  485.                                  unsigned char *      cm_conv_id);
  486. int    cpicerr_set_log_file_name(CPICERR *            cpicerr,
  487.                                  char *               log_file_name);
  488. int    cpicerr_set_log_file_path(CPICERR *            cpicerr,
  489.                                  char *               log_file_path);
  490. int    cpicerr_set_exit_level(   CPICERR *            cpicerr,
  491.                                  CPIC_RC_HANDLING     exit_level);
  492. int    cpicerr_set_show_level(   CPICERR *            cpicerr,
  493.                                  CPIC_RC_HANDLING     show_level);
  494. int    cpicerr_set_log_level(    CPICERR *            cpicerr,
  495.                                  CPIC_RC_HANDLING     log_level);
  496. CPIC_RC_HANDLING
  497. cpicerr_handle_rc_extended(      CPICERR *            cpicerr,
  498.                                  CPIC_VERB_INDEX      verb_index,
  499.                                  CM_RETURN_CODE       conv_rc,
  500.                                  char *               file_name,
  501.                                  int                  file_line);
  502. /*
  503.  * Provide an alternative interface for handling unexpected CPI-C
  504.  * return codes.  This macro saves the programming from having
  505.  * to type the __FILE__ and __LINE__ macros for each call.
  506.  */
  507. #define cpicerr_handle_rc(x,y,z)                    \
  508.         cpicerr_handle_rc_extended(x,y,z, __FILE__, __LINE__)
  509.  
  510. int    cpicerr_exchange_version( CPICERR *            cpicerr,
  511.                                  unsigned char *      cm_conv_id,
  512.                                  CM_INT32             conv_state,
  513.                                  unsigned char *      partner_major_version,
  514.                                  unsigned char *      partner_minor_version);
  515. int    cpicerr_exchange_version_plus(
  516.                                  CPICERR *            cpicerr,
  517.                                  unsigned char *      cm_conv_id,
  518.                                  CM_INT32             conv_state,
  519.                                  unsigned char *      partner_major_version,
  520.                                  unsigned char *      partner_minor_version,
  521.                                  unsigned char *      opsys_string,
  522.                                  unsigned int         opsys_string_length);
  523. void   cpicerr_destroy(          CPICERR *            cpicerr);
  524.  
  525.  
  526.  
  527. #endif
  528.