═══ 1. About RXAPPCFD ═══

RXAPPCFD allows Rexx programs to use the APPC programming interface provided by 
CM/2 v1.1, which includes support for full-duplex conversations. This has been 
developed with a Beta version of CM/2 v1.1. 

Thanks to Sam Detweiler after whose "RXAPPC" function package I modeled 
RXAPPCFD. 


  Author:        Dave Boll
                 (CompuServe = 74170,2016)
                 IBMMAIL(USFMCFKF)
  Release Date:  18 November, 1993
  Version:       1.1

  Copyright 1993 Dave Boll


═══ 2. Release Notes ═══

This is the second release (v1.1).  This function package works on ES Comm. 
Mgr. as well as on previous versions of CM/2 (v1.0), although full-duplex 
conversations will only be supported on CM/2 v1.1 and above. 

New in version 1.1:

  - The character set specified by the "Set_Internal_Conversion_Charset"
    function now applies to internal conversion of USERID and PASSWORD values.
    (thanks to Thomas Theurer for suggesting this)


═══ 3. General Information ═══

General information about RXAPPCFD. 


═══ 3.1. How to Use It ═══

How to register the functions: 

In order to use the functions, you have to register them with Rexx like this:

  call rxfuncadd 'rxappcfd','rxappcfd','rxappcfd'

The .DLL "rxappcfd.dll" must be in your libpath.


═══ 3.2. Return codes ═══

Return codes for all verbs are as such: 


  appcrc = rxappcfd(verb,...)

where

  appcrc = 1 to 4 blank delimited values:

           1) primary return code
           2) secondary return code (if non-zero and (1) is non-zero)
           3) sense code (if non-zero, on allocate/sendconversation only)
           4) API duration in milliseconds (only if you ask for timing)


═══ 3.3. Case Sensitivity of Parameters ═══

Some parameters are case sensitive, some are not. 

- The case of the verb parameter (first argument) is not important.
- The case of the conversation-type (usually second argument) is not
  important.


═══ 3.4. Multi-threaded applications ═══

RXAPPCFD supports multi-threaded Rexx applications (i.e. may be called by Rexx 
programs running on multiple threads of the same process). 

Settings like "Internal_Conversion_Charset", "Autoconvert", and "Call_Timing" 
are unique to a thread (including initial default values). 

This means that if thread "n" uses RXAPPCFD, then ends, and then another thread 
of the same thread-id ("n") is started in that process, this second instance of 
thread "n" will inherit the settings from the first instance (i.e. the default 
settings may no longer be in effect). 


═══ 4. RXAPPCFD service functions ═══

Functions specific to RXAPPCFD 


═══ 4.1. Set_Internal_Conversion_Charset ═══

Set_Internal_Conversion_Charset causes all subsequent internal conversions (of 
Tp_Name, Userid, Password) to use the specified character set. 

Syntax:

  currcs = rxappcfd('Set_Internal_Conversion_Charset',charset)

where:

  charset = character set to use for internal conversions:
            A - SV_A
            E - SV_AE
            G - SV_G
  currcs  = charset in effect before this call (initially "E")


═══ 4.2. Set_Autoconvert ═══

Set_Autoconvert causes ASCII<->EBCDIC translation of the entire data buffer on 
send and receive verbs (A->E on send, E->A on receive). 

Syntax:

  currval = rxappcfd('Set_Autoconvert',val)

where:

  val     = 'Yes' or 'No'
  currval = setting before this call (initially "No")


═══ 4.3. Set_Call_Timing ═══

Set_Call_Timing causes each verb execution to be timed, with the millisecond 
time value returned as part of the return value of the verb's execution (see 
"Return Codes" above). 

Syntax:

  currval = rxappcfd('Set_Call_Timing',val)

where:

  val     = 'Yes' or 'No'
  currval = setting before this call (initially "No")


═══ 5. APPC Service Verbs ═══

APPC service verbs which are conversation type/style independent. 


═══ 5.1. Receive_Allocate ═══

Receive_Allocate 

Syntax:

  appcrc = rxappcfd('receive_allocate',tpname,rexxstem)

where:

  tpname   = name of tp for which incoming allocate should be received
  rexxstem = name of rexx stem under which data is returned:
             stem.1  = tpid
             stem.2  = convid
             stem.3  = sync_level
                       None
                       Confirm
             stem.4  = conv_type
                       B   - Basic
                       M   - Mapped
             stem.5  = userid
             stem.6  = lu_alias
             stem.7  = plu_alias
             stem.8  = mode_name
             stem.9  = conv_group_id
             stem.10 = fqplu_name
             stem.11 = pip_incoming
             stem.12 = conv_style
                       A - Two way alternate
                       S - Two way simultaneous


═══ 5.2. Tp_Started ═══

Tp_Started 

Syntax:

  appcrc = rxappcfd('tp_started',loclu,tpname,rexxvar)

where:

  loclu   = name of local lu (default local lu if no supplied)
  tpname  = name of local tp to start (1-64 chars)
  rexxvar = name of rexx variable in which tpid is returned


═══ 5.3. Tp_Ended ═══

Tp_Ended 

Syntax:

  appcrc = rxappcfd('tp_ended',tpid,type)

where:

  tpid    = tpid (returned from tp_started)
  type    = 'Hard' or 'Soft'


═══ 5.4. Convert ═══

Converts between ASCII and EBCDIC using specified conversion set. 

Syntax:

  appcrc = rxappcfd('convert',direction,charset,data,rexxvar)

where:

  direction = what data is to be converted TO:
              E - convert ASCII to EBCDIC
              A - convert EBCDIC to ASCII
  charset   = what conversion character set to use:
              E - SV_AE
              A - SV_A
              G - SV_G
  data      = actual data to be converted
  rexxvar   = name of rexx variable into which converted result is
              placed.


═══ 5.5. Get_Tp_Properties ═══

Get_Tp_Properties 

Syntax:

  appcrc = rxappcfd('get_tp_properties',tpid,rexxstem)

where:

  tpid     = tpid (returned from tp_started)
  rexxstem = name of rexx stem under which information is returned:
             stem.1   = tpname
             stem.2   = lu_alias
             stem.3   = fqlu_name
             stem.4   = fqluw_name
             stem.4.1 = luwid_instance
             stem.4.2 = luwid_sequence
             stem.5   = userid


═══ 5.6. Get_Type ═══

Get_Type 

Syntax:

  appcrc = rxappcfd('get_type',tpid,convid,rexxstem)

where:

  tpid     = tpid (returned from tp_started)
  convid   = conversation-id from allocate or receive_allocate
  rexxstem = name of rexx stem under which information is returned:
             stem.1   = convtype:
                        B   = Basic conversation (half-duplex non-blocking)
                              (Basic conversation prior to CM/2 v1.1)
                        BN  = Basic Non-Blocking
                        BFB = Basic Full-Duplex Blocking
                        BFN = Basic Full-Duplex Non-Blocking
                        M   = Mapped conversation (half-duplex non-blocking)
                              (Mapped conversation prior to CM/2 v1.1)
                        MN  = Mapped Non-Blocking
                        MFB = Mapped Full-Duplex Blocking
                        MFN = Mapped Full-Duplex Non-Blocking
             stem.2   = convstyle:
                        A - Two Way Alternate
                        S - Two Way Simultaneous


═══ 6. APPC Conversation Verbs ═══

APPC conversation verbs which are conversation type/style dependent. 


The argument list for APPC Conversation Verbs is of the form:

  appcrc = rxappcfd(verb,convtype,...)

where:

  verb     = the specific appc verb
  convtype = indicates type of conversation:

             B   = Basic conversation (half-duplex non-blocking)
                   (also "BASIC")
                   (Basic conversation prior to CM/2 v1.1)
             BN  = Basic Non-Blocking
             BFB = Basic Full-Duplex Blocking
             BFN = Basic Full-Duplex Non-Blocking
             M   = Mapped conversation (half-duplex non-blocking)
                   (also "MAPPED")
                   (Mapped conversation prior to CM/2 v1.1)
             MN  = Mapped Non-Blocking
             MFB = Mapped Full-Duplex Blocking
             MFN = Mapped Full-Duplex Non-Blocking


═══ 6.1. Allocate ═══

Allocate 

Syntax:

  appcrc = rxappcfd('allocate',convtype,tpid,synclvl,retctl,convstyle
                   ,plu,modename,tpname,security,rexxstem)

where:

  tpid      = tpid obtained from 'tp_started'
  synclvl   = synchronization level:
              N - none
              C - confirm
  retctl    = return control:
              A - when session allocated
              I - immediate
              F - when session free
              G - when conv-group allocated
              W - when conwinner allocated
  convstyle = conversation style:
              A - two way alternate
              S - two way simultaneous
  plu       = partner lu:
                plu-alias
                  or
                fully qualified plu (contains a dot '.')
  modename  = mode name
  tpname    = name of partner tp (case sensitive)
  security  = conversation security:
              NONE
              SAME
              PGM userid password
  rexxstem  = name of rexx stem variable under which info is returned:
              stem.1 = convid
              stem.2 = convgroupid


═══ 6.2. Confirm ═══

Confirm 

Syntax:

  appcrc = rxappcfd('confirm',convtype,tpid,convid,rexxstem)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  rexxstem  = name of rexx stem variable under which info is returned:
              stem.1 = request-to-send-received? (Y/N)
              stem.2 = expedited-data-received? (Y/N)


═══ 6.3. Confirmed ═══

Confirmed 

Syntax:

  appcrc = rxappcfd('confirmed',convtype,tpid,convid)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate


═══ 6.4. Deallocate ═══

Deallocate 

Syntax:

  appcrc = rxappcfd('deallocate',convtype,tpid,convid,type,rexxvar)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  type      = deallocate type:
              S - sync_level
              F - flush
              P - abend_prog
              V - abend_svc
              T - abend_timer
  rexxvar   = name of rexx variable into which "expedited_data_received"
              value is placed:
              Y - Yes
              N - No


═══ 6.5. Flush ═══

Flush 

Syntax:

  appcrc = rxappcfd('flush',convtype,tpid,convid)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate


═══ 6.6. Get_Attributes ═══

Get_Attributes 

Syntax:

  appcrc = rxappcfd('get_attributes',convtype,tpid,convid,rexxstem)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  rexxstem  = name of rexx stem under which info is returned:
              stem.1  = sync level:
                        N - None
                        C - Confirm
              stem.2  = mode name
              stem.3  = net name
              stem.4  = lu_name
              stem.5  = lu_alias
              stem.6  = plu_alias
              stem.7  = plu_unqualified_name
              stem.8  = fqplu_name
              stem.9  = userid
              stem.10 = conv_group_id
              stem.11 = conv_corr_id


═══ 6.7. Prepare_To_Receive ═══

Prepare_To_Receive 

Syntax:

  appcrc = rxappcfd('prepare_to_receive',convtype,tpid,convid,ptrtype
                   ,locks)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  ptrtype   = prepare_to_receive type:
              S - sync_level
              F - flush
  locks     = 'Short' or 'Long'


═══ 6.8. Receive_And_Post ═══

Receive_And_Post 

Syntax:

  appcrc = rxappcfd('receive_and_post',convtype,tpid,convid,rswd
                   ,maxlen,sem,rexxstem[,filltype])

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  rswd      = return status with data:
              Y - Yes
              N - No
  maxlen    = max length of data to receive
  sem       = semaphore handle
  rexxstem  = name of rexx stem under which info is returned:
              stem.1 = Status Received:
                       N  - None
                       S  - Send
                       C  - Confirm
                       CS - ConfirmSend
                       CD - ConfirmDeallocate
              stem.2 = Data Received:
                       N    - None
                       D    - Data
                       DC   - DataComplete
                       DI   - DataIncomplete
                       UCDC - UCDataComplete
                       UCDI - UCDataInomplete
              stem.3 = request_to_send_received:
                       Y - Yes
                       N - No
              stem.4 = expedited_data_received:
                       Y - Yes
                       N - No
              stem.5 = the actual data received
  filltype  = for Basic conversations only:
              B - Buffer
              L - LL


═══ 6.9. Receive_And_Wait ═══

Receive_And_Wait 

Syntax:

  appcrc = rxappcfd('receive_and_wait',convtype,tpid,convid,rswd
                   ,maxlen,rexxstem[,filltype])

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  rswd      = return status with data:
              Y - Yes
              N - No
  maxlen    = max length of data to receive
  rexxstem  = name of rexx stem under which info is returned:
              stem.1 = Status Received:
                       N  - None
                       S  - Send
                       C  - Confirm
                       CS - ConfirmSend
                       CD - ConfirmDeallocate
              stem.2 = Data Received:
                       N    - None
                       D    - Data
                       DC   - DataComplete
                       DI   - DataIncomplete
                       UCDC - UCDataComplete
                       UCDI - UCDataInomplete
              stem.3 = request_to_send_received:
                       Y - Yes
                       N - No
              stem.4 = expedited_data_received:
                       Y - Yes
                       N - No
              stem.5 = the actual data received
  filltype  = for Basic conversations only:
              B - Buffer
              L - LL


═══ 6.10. Receive_Expedited_Data ═══

Receive_Expedited_Data 

Syntax:

  appcrc = rxappcfd('receive_expedited_data',convtype,tpid,convid
                   ,retctl,maxlen,rexxstem)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  retctl    = return control:
              R - when expedited data received
              I - immediately
  maxlen    = max length of data to receive
  rexxstem  = name of rexx stem under which info is returned:
              stem.1 = request_to_send_received:
                       Y - Yes
                       N - No
              stem.2 = expedited_data_received:
                       Y - Yes
                       N - No
              stem.3 = the actual data received
  filltype  = for Basic conversations only:
              B - Buffer
              L - LL


═══ 6.11. Receive_Immediate ═══

Receive_Immediate 

Syntax:

  appcrc = rxappcfd('receive_immediate',convtype,tpid,convid,rswd
                   ,maxlen,rexxstem[,filltype])

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  rswd      = return status with data:
              Y - Yes
              N - No
  maxlen    = max length of data to receive
  rexxstem  = name of rexx stem under which info is returned:
              stem.1 = Status Received:
                       N  - None
                       S  - Send
                       C  - Confirm
                       CS - ConfirmSend
                       CD - ConfirmDeallocate
              stem.2 = Data Received:
                       N    - None
                       D    - Data
                       DC   - DataComplete
                       DI   - DataIncomplete
                       UCDC - UCDataComplete
                       UCDI - UCDataInomplete
              stem.3 = request_to_send_received:
                       Y - Yes
                       N - No
              stem.4 = expedited_data_received:
                       Y - Yes
                       N - No
              stem.5 = the actual data received
  filltype  = for Basic conversations only:
              B - Buffer
              L - LL


═══ 6.12. Request_To_Send ═══

Request_To_Send 

Syntax:

  appcrc = rxappcfd('request_to_send',convtype,tpid,convid)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate


═══ 6.13. Send_Conversation ═══

Send_Conversation 

Syntax:

  appcrc = rxappcfd('send_conversation',convtype,tpid,retctl,plu
                   ,modename,tpname,security,data,rexxstem)

where:

  tpid      = tpid obtained from 'tp_started'
  retctl    = return control:
              A - when session allocated
              I - immediate
              F - when session free
              G - when conv-group allocated
              W - when conwinner allocated
  plu       = partner lu:
                plu-alias
                  or
                fully qualified plu (contains a dot '.')
  modename  = mode name
  tpname    = name of partner tp (case sensitive)
  security  = conversation security:
              NONE
              SAME
              PGM userid password
  data      = actual data to be sent
  rexxstem  = name of rexx stem variable under which info is returned:
              stem.1 = convgroupid


═══ 6.14. Send_Data ═══

Send_Data 

Syntax:

  appcrc = rxappcfd('send_data',convtype,tpid,convid,type,data,rexxstem)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  type      = send type:
              N    - None
              F    - Flush
              C    - Confirm
              PTRF - Prepare To Receive Flush
              PTRS - Prepare To Receive Sync Level
              DF   - Deallocate Flush
              DS   - Deallocate Sync Level
              DA   - Deallocate Abend
  data      = actual data to be sent
  rexxstem  = name of rexx stem variable under which info is returned:
              stem.1 = request-to-send-received? (Y/N)
              stem.2 = expedited-data-received? (Y/N)


═══ 6.15. Send_Error ═══

Send_Error 

Syntax:

  appcrc = rxappcfd('send_error',convtype,tpid,convid,type,errdir
                   ,rexxstem)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  type      = send type:
              P - Prog
              S - Svc
  errdir    = error direction:
              R - Receive
              S - Send
  rexxstem  = name of rexx stem variable under which info is returned:
              stem.1 = request-to-send-received? (Y/N)
              stem.2 = expedited-data-received? (Y/N)


═══ 6.16. Send_Expedited_Data ═══

Send_Expedited_Data 

Syntax:

  appcrc = rxappcfd('send_expedited_data',convtype,tpid,convid,data
                   ,rexxstem)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate
  data      = actual data to be sent
  rexxstem  = name of rexx stem variable under which info is returned:
              stem.1 = request-to-send-received? (Y/N)
              stem.2 = expedited-data-received? (Y/N)


═══ 6.17. Test_Rts ═══

Test_Rts 

Syntax:

  appcrc = rxappcfd('test_rts',convtype,tpid,convid)

where:

  tpid      = tpid obtained from tp_started or receive_allocate
  convid    = conversation-id from allocate or receive_allocate