Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer Guide

Chapter 8: CPIC Command Reference

Back to Table of Contents


Introduction

Overview

This section defines the CPIC built-in statements, describes their usage, and includes any notes that may be helpful.

The statements are listed in alphabetical order.

Many of the statements use Tivoli Service Desk (TSD) Developer's Toolkit system-defined constants.

For each statement, the following information is provided, when it is available:

CPICAccept

Description

Accepts an incoming CPIC or APPC conversation.

Parameters

conv: CONVERSATION

Parameter notes

Parameter Description
conv Conversation handle to initialize with the incoming conversation characteristics

Return type

INTEGER

Notes

This call initializes values for various conversation characteristics. The caller of this function is considered the "receiver" of the conversation.

Each CPIC conversation is identified by the CONVERSATION handle that is initialized by CPICAccept. The TSD Script application uses this handle in CPIC calls intended for that conversation. The application must issue a CPICAccept statement before any other calls can refer to the conversation.

Currently, CPIC allows an application to accept only one conversation, although there is no limit on the number of conversations one application can allocate.

Example

The following two applications, FIRST and SECOND, transfer a text file. SECOND is the initiator of the conversation.

-- FIRST.KB 
-- This application is the receiver of a file transfer. 
-- The file will be sent one text line at a time. 
-- After the transfer is complete, the routine will
   send back the entire file in one buffer 
   (this return trip will only work for files < 32K). 
KNOWLEDGEBASE FIRST; 
ROUTINES 
   PROCEDURE GetConversation; 
PRIVATE 
TYPES 
FileRec IS RECORD 
LineNbr:INTEGER; 
Buff:STRING; 
END; 
ROUTINES 
PROCEDURE GetConversation IS 
VARIABLES 
   Conv      :CONVERSATION; 
   Buff      :STRING; 
   FileLine  :FileRec; 
   TotalBuff :STRING; 
   DataRcvd  :INTEGER; 
   StatRcvd  :INTEGER; 
   ReqTSRcvd :INTEGER; 
   didreqts  :BOOLEAN; 
   rc        :INTEGER; 
   count     :INTEGER; 
ACTIONS 
   rc         := CPICAccept(Conv); 
   TotalBuff  := ''; 
   count      := 0; 
   didreqts   := FALSE; 
   while (rc = 1) and (not(StatRcvd = 1)) do 
          rc  := CPICReceive(Conv,'FILEREC.DDF',
                            FileLine,DataRcvd,StatRcvd,
                            ReqTSRcvd); 
       if ((DataRcvd = $CPICDataReceived) or 
          (DataRcvd = $CPICCompleteDataReceived)) then 
         TotalBuff := TotalBuff & FileLine.Buff; 
       end; 
       count := count + 1; 
       if ((StatRcvd = $CPICConfirmReceived) or 
          (StatRcvd  = $CPICConfirmSendReceived)) then 
                 rc := CPICConfirmed(Conv); 
       end; 
       if (count = 3) then 
          rc := CPICRequestToSend(Conv); 
          didreqts := TRUE; 
       end; 
       if (((StatRcvd = $CPICConfirmSendReceived) or 
            (StatRcvd = $CPICSendReceived)) and 
            (didreqts)) then 
               Buff     := 'DATA SENT BY FIRST.KB AFTER 
                            REQUEST TO SEND'; 
               rc       := CPICSend(Conv,'STD3.DDF',
                                 Buff,ReqTSRcvd); 
               Buff     := 'DO RAY ME FA LA SO.'; 
               rc       := CPICSend(Conv,'STD3.DDF',
                                 Buff,ReqTSRcvd); 
               rc       := CPICPrepareToReceive(Conv); 
               didreqts := FALSE; 
               StatRcvd := 0; 
            end; 
       end; 
       rc := CPICSend(Conv,'TOTALBUF.DDF',TotalBuff, 
                      ReqTSRcvd); 
       rc := CPICDeallocate(Conv); 
    END; 
    -- SECOND.KB 
    -- This file reads in a text file, transmitting each
       line to FIRST. 
    -- When finished, SECOND will receive the entire file
       in one buffer from FIRST. 
KNOWLEDGEBASE SECOND; 
ROUTINES 
    PROCEDURE DoConversation(VAL Args:List of String); 
    (* Expecting sdn, infile *) 
PRIVATE 
ROUTINES 
PROCEDURE RcvData(VAL Conv:Conversation) IS 
VARIABLES 
    Buff      :STRING; 
    DataRcvd  :INTEGER; 
    StatRcvd  :INTEGER; 
    ReqTSRcvd :INTEGER; 
    rc        :INTEGER; 
ACTIONS 
    rc := 1; 
    while (rc = 1) and (not((StatRcvd =
                        $CPICSendReceived) or 
                       (StatRcvd =
                        $CPICconfirmSendReceived))) do 
                       rc := CPICReceive(Conv,'STD.DDF',
                                         Buff,DataRcvd,StatRcvd,
                                         ReqTSRcvd); 
                       if ((StatRcvd = $CPICConfirmReceived) or 
                          (StatRcvd = $CPICConfirmSendReceived)) then 
                          rc := CPICConfirmed(Conv); 
                       end; 
    end; 
END; -- RcvData 
PROCEDURE DoConversation(VAL Args:List of String) IS 
VARIABLES 
   Conv      :Conversation; 
   Buff      :STRING; 
   DataRcvd  :INTEGER; 
   StatRcvd  :INTEGER; 
   ReqTSRcvd :INTEGER; 
   rc        :INTEGER; 
   inf       :file; 
ACTIONS 
   if (ListLength(Args) < 3) then 
       WinMessageBox($DESKTOP,'Oops',$MBOK,
       'KML SECOND SDN INFILE'); 
      Exit; 
   end; 
   FOpen(inf,Args[2],$Read); 
   rc := CPICInitialize(Conv,Args[1]); 
   rc := CPICSetSyncLevel(Conv, $CPICConfirm); 
   rc := CPICSetTPName(Conv,'RUNRCV '); 
   rc := CPICSetPartnerLUName(Conv,'SAI.DVORJAK '); 
   rc := CPICSetConvType(Conv,$CPICBasicConversation); 
   rc := CPICAllocate(Conv); 
   rc := CPICSetSendType(Conv, $CPICBufferData); 
   rc := CPICSetPrepareToReceiveType
         (Conv,$CPICPrepToReceiveFlush); 
   while (FReadLn(inf,Buff) > 0) do 
      Buff:= Buff & Char(13) & Char(10); -- add on CR LF 
      rc := CPICSend(Conv,'FILEREC.DDF',
                     Buff,ReqTSRcvd); 
      if (ReqTSRcvd = $CPICReqToSendReceived) then 
          RcvData(Conv); 
      end; 
   -- the confirms have been randomized 
      for this example 
   if (random(1,10) < 2) then 
       CPICConfirm(Conv,ReqTSRcvd); 
       if (ReqTSRcvd = $CPICReqToSendReceived) then 
           RcvData(Conv); 
       end; 
    end; 
 end; 
 FClose(inf); 
 rc := CPICPrepareToReceive(Conv); 
 rc := CPICReceive(Conv,'TOTALBUF.DDF',
                   Buff,DataRcvd,StatRcvd,ReqTSRcvd); 
 rc := CPICDeallocate(Conv); 
END; 

See also

CPICAllocate

Description

Establishes a basic or mapped conversation with a partner application.

Parameters

conv: CONVERSATION EXPRESSION 

Parameter notes

Parameter Description
conv The conversation that has been initialized and is to be allocated

Return type

INTEGER

Notes

After issuing this call, an application is in Send state.

An application must issue the CPICInitialize command (with the same CONVERSATION variable) before attempting CPICAllocate.

The partner application is specified in the TP name characteristic of the CPIC side information SDN designated in the call to CPICInitialize. Before issuing CPICAllocate (and after issuing CPICInitialize), a TSD Script application may issue one of the following calls:

The local LU may buffer an allocation request until it accumulates enough information for transmission (from one or more CPICSend calls), or until the local TSD Script application issues a call that explicitly flushes the buffer.

The local application can issue a CPICFlush immediately after the CPICAllocate in order to make sure the connection.

After accepting the conversation, the remote application is in Receive state.

Allocation errors

An allocation error resulting from a failure at the local LU is reported on the call to CPICAllocate.

An allocation error resulting from the rejection of the request at the partner LU is reported on a subsequent conversation call.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICConfirm

Description

Requests confirmation (on receipt of data) from the partner application, then waits for a reply.

Parameters

conv : CONVERSATION EXPRESSION 
reqTSRcvd: INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation that has been initialized and is to be allocated
reqTSRcvd Indicates whether or not the partner has requested to send data. This variable has the value $CPICRequestToSendReceived or $CPICRequestToSendNotReceived:
  • $CPICRequestToSendReceived means the partner has issued a CPICRequestToSend. This is a request that the local application enter receive state.
  • $CPICRequestToSendNotReceived means the partner has not issued a CPICRequestToSend. The local application is free to remain in send state.

Return type

INTEGER

Notes

The local application pauses further processing until the partner application replies to this request. The local LU's send buffer is flushed by this call.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICConfirmed

Description

Replies to a confirmation request by the partner.

Parameters

conv: CONVERSATION EXPRESSION 

Parameter notes

Parameter Description
conv The conversation that has been initialized and is to be allocated

Return type

INTEGER

Notes

This function should only be called when the partner has requested confirmation.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICConfirm

CPICDeallocate

Description

Ends a conversation and frees the resources dedicated to that conversation.

Parameters

conv: CONVERSATION EXPRESSION 

Parameter notes

Parameter Description
conv The conversation that has been initialized and is to be allocated

Return type

INTEGER

Notes

The local LU's send buffer is flushed by this function.

The partner receives notification of the deallocation by means of a return code or the statusReceived parameter of CPICReceive.

If the statusReceived parameter is $CPICConfirmDeallocReceived, the local application issued the CPICDeallocate with:

Example

See the code segment for CPICAccept for a complete example.

See also

CPICDeleteSideInfo

Description

Deletes the designated CPIC side information entry.

Parameters

keylock : STRING EXPRESSION 
symDestName: STRING EXPRESSION

Parameter notes

Parameter Description
keylock The Communications Manager key, when the Communications Manager keylock feature is turned on. Specify ' ' (eight blanks) when you do not use this feature.
symDestName The SDN of the entry in the Communications Manager setup information

Return type

INTEGER

If the return code is anything other than one, the entry has not been deleted.

Notes

This call does not affect an active conversation. The entry is removed immediately, meaning any subsequent CPICInitialize calls made with the SDN are rejected. While Communications Manager is removing the entry, any other application's attempt at CPICInitialize is suspended until the removal is completed.

See also

CPICExtractConvSecurityType

Description

Obtains the security type for the conversation.

Parameters

conv            : CONVERSATION 
convSecurityType: INTEGER PARAMETER 

Parameter notes

Parameter Description
conv Specifies the conversation for which the security type is being checked
convSecurityType Contains the integer signifying the security type TSD Script has system constants that are mnemonics for these types:
  • $CPICSecurityNone
  • $CPICSecuritySame
  • CPICSecurityProgram

Return type

INTEGER

Notes

The security type for a conversation is set to a default value on the call to CPICInitialize. It can be changed with a call to CPICSetConvSecurityType.

See also

CPICExtractConvSecurityUserID

Description

Obtains the security user ID associated with a conversation.

Parameters

conv : CONVERSATION EXPRESSION 
securityUserID: STRING PARAMETER 

Parameter notes

Parameter Description
conv The conversation handle for the security user ID
securityUserID Contains the ID of the user with access to the conversation

Return type

INTEGER

Notes

The security user ID is set to a default value on the call to CPICInitialize. It can be changed with a call to CPICSetConvSecurityUserID.

See also

CPICExtractConvState

Description

Obtains the state of the given conversation.

Parameters

conv : CONVERSATION EXPRESSION 
state: INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation handle for which you wish to know the state
state Contains the state of the conversation for the local partner TSD Script system constants are:
  • $CPICInitState
  • $CPICSendState
  • $CPICReceiveState
  • $CPICSendPendingState
  • $CPICConfirmState
  • $CPICConfirmSendState
  • $CPICConfirmDeallocateState

Return type

INTEGER

CPICExtractConvType

Design

Obtains the type of the given conversation.

Parameters

conv     : CONVERSATION PARAMETER 
convType : INTEGER PARAMETER 

Parameter notes

Parameter Description
conv Conversation handle whose type is desired.
convType Contains the type of the conversation. The value may be one of the following TSD Script system constants:
  • $CPICBasicConversation
  • $CPICMappedConversation

Return type

INTEGER

Notes

The type of the conversation defaults to $CPICMappedConversation during CPICInitialize processing.

Calling CPICSetConvType after CPICInitialize is called (and before CPICAllocate is called) alters the conversation type.

See also

CPICSetConvType

CPICExtractModeName

Description

Obtains the mode name for the given conversation.

Parameters

conv     : CONVERSATION EXPRESSION 
modeName : STRING PARAMETER 

Parameter notes

Parameter Description
conv The conversation handle for which the mode name is desired
modeName Contains the mode name of the conversation. This designates the network properties for the session carrying the conversation.

Return type

INTEGER

See also

CPICSetModeName

CPICExtractPartnerLUName

Description

Obtains the partner application's LU name.

Parameters

conv          : CONVERSATION EXPRESSION 
partnerLUName : STRING PARAMETER 

Parameter notes

Parameter Description
conv Indicates the conversation to the partner application for which you want the LU name
partnerLUName Contains the LU name of the partner

Return type

INTEGER

See also

CPICSetPartnerLUName

CPICExtractSideInfo

Description

Obtains the parameters for the indicated SDN.

Parameters

entryNbr         : INTEGER EXPRESSION 
symDestName      : STRING EXPRESSION 
partnerLUName    : STRING PARAMETER 
TPNameType       : INTEGER PARAMETER 
TPName           : STRING PARAMETER 
modeName         : STRING PARAMETER 
convSecurityType : INTEGER PARAMETER 
securityUserID   : STRING PARAMETER 

Parameter notes

Parameter Description
entryNbr The index number in the CPIC Side Information table for which values are needed. If this number is 0, the Communications Manager searches based on the SDN given.
symDestName When you specify 0 for the entryNbr, this value is used to search the CPIC Side Information table.
partnerLUName The partner LU name specified in the CPIC side information entry.
TPNameType An integer indicating the type of the TP. The TSD Script system constants for these types are $CPICApplicationTP and $CPICSNAServiceTP.
TPName The name of the TP.
modeName The mode used in any conversations allocated using this SDN.
convSecurityType The type of security used for any conversations allocated with this CPIC side information entry.
securityUserID The user ID for security access to the conversation. This is passed to the partner LU during an allocation request, when the security type is CPICSecurityProgram.

Return type

INTEGER

Notes

The security password of the table entry is not returned.

While Communications Manager is carrying out this command, any other application's calls to change this information are suspended.

The entry number specifies an index into the current list of internal CPIC Side Information entries. If entries are deleted, the indexes change.

See also

CPICExtractSyncLevel

Description

Obtains the current sync level for the conversation.

Parameters

conv      : CONVERSATION EXPRESSION 
SYNCLEVEL : INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation handle for which the sync level is required.
SYNCLEVEL The current synchronization level of the specified conversation.

The TSD Script system constant mnemonics for these values are:

Return type

INTEGER

Notes

A sync level value of $CPICNone indicates that the partners do not perform confirmation processing.

A sync level value of $CPICConfirm means that the applications perform confirmation processing. That is, they issue appropriate confirmation calls and recognize returned parameters relating to confirmation.

See also

CPICSetSyncLevel

CPICFlush

Description

Causes the Communications Manager to send any data in the internal buffers.

Parameters

conv: CONVERSATION EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for flushed data

Return type

INTEGER

Notes

When an application issues a CPICAllocate, CPICSend, or CPICSendError, Communications Manager may store the data internally to make network traffic as efficient as possible. Communications Manager holds the data until either the internal buffer becomes full, or the application forces a flush. If there is no data in the internal buffer, no data is sent to the partner application.

An application can force a flush either explicitly, with CPICFlush, or implicitly, with CPICConfirm, CPICPrepareToReceive, CPICDeallocate, and so on.

If you plan on flushing after every CPICSend, you may want to use the CPICSetSendType to set the send type to $CPICSendAndFlush. Be aware that by doing this you are circumventing the efficiency measures that Communications Manager attempts to take.

See also

CPICInitialize

Description

Configures and prepares internal resources for a conversation. Many characteristics are set to default values and associated with the specified conversation handle.

Parameters

conv : CONVERSATION PARAMETER 
symDestName: STRING EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle to be prepared for a conversation.
symDestName The SDN of an entry in the CPIC Side Information table to be used in setting the characteristics for the conversation.

Return type

INTEGER

Notes

An application can override the attributes initialized in this call by calling the appropriate CPICSet calls. Remember that these set calls must be made before the call to CPICAllocate.

The conversation handle configured by this command is used in all subsequent calls to CPIC commands. An application can carry multiple conversations by calling CPICInitialize once for each conversation to be allocated.

If the CPIC Side Information table provides invalid information for the conversation, this condition is detected on the call to CPICAllocate.

An application may provide a blank symDestName to this function. By doing so, the application becomes responsible for calling the TSD Script functions to set the conversation characteristics.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICPrepareToReceive

Description

Changes the local end of the conversation from Send state to Receive state, as a preparation to receive data.

Parameters

conv: CONVERSATION EXPRESSION 

Parameter notes

Parameter Description
conv The handle identifying the conversation to be put in Receive state.

Return type

INTEGER

Notes

If the prepare to receive type for the conversation is $CPICPrepareToReceiveConfirm, or the prepare to receive type is $CPICPrepareToReceiveSyncLevel and sync level is $CPICConfirm, Communications Manager sends a confirmation request to the partner application.

The local application waits until a confirmed reply is received. This command implicitly forces a flush.

The remote application receives notification of send control by means of the status received parameter.

For a status received value of $CPICSendReceived, the local application issued the CPICPrepareToReceive command with no confirmation requested.

For $CPICConfirmSendReceived, the local application issues the command with confirmation requested--this is done by either having a prepare to receive type set to $CPICPrepToReceiveConfirm, or $CPICPrepToReceiveSyncLevel with sync level set to $CPICConfirm.

The remote application's end of the conversation begins a Send or Send-Pending state.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICReceive

Description

Receives incoming data from the specified conversation.

Parameters

conv          : CONVERSATION EXPRESSION 
DDFName       : STRING EXPRESSION 
buffer        : ANY PARAMETER 
dataReceived  : INTEGER PARAMETER 
statusReceived: INTEGER PARAMETER 
reqTSRcvd     : INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation handle from which to get the data.
DDFName The name of the DDF which defines the structure of the incoming block of bytes.
buffer A TSD Script variable of either a simple type (INTEGER, BOOLEAN, TIME, DATE, STRING) or a user-defined record type. This variable is closely related to the DDFName parameter, because the DDFName should specify a DDF which adequately describes the buffer format.
dataReceived Specifies whether the application received any data.

The TSD Script system constants for this value are as follows:

  • $CPICNoDataReceived means no data bytes were sent. Status may have been received.
  • $CPICCompleteDataReceived means a complete data record was received.
  • statusReceived indicates the conversation status. The following TSD Script system constants apply:
    • $CPICNoStatusReceived means no conversation status was received. Data may have been received.
    • $CPICSendReceived means the remote application is now in Receive state, placing the local application in Send-Pending state (if data was also received on this call) or Send state (if no data was received). The local application can now send data using.
    • CPICSend.$CPICConfirmReceived means the remote application has requested confirmation of the data sent. The local application should respond by issuing CPICConfirmed, CPICSendError, or CPICDeallocate with deallocate type set to $CPICDeallocateAbend.
    • $CPICConfirmSendReceived means the remote application entered the Receive state with confirmation requested.
    • $CPICConfirmDeallocReceived means the remote application has deallocated the conversation with confirmation requested. On issuing CPICConfirmed, the local application is now in Reset state.
reqTSRcvd Indicates whether or not the partner has requested to send data. This variable has the value $CPICRequestToSendReceived or $CPICRequestToSendNotReceived. $CPICRequestToSendReceived means the partner has issued a CPICRequestToSend. This is a request that the local application enter Receive state.
  • $CPICRequestToSendNotReceived means the partner has not issued a CPICRequestToSend. The local application is free to remain in Send state.

Return type

INTEGER

Notes

If the receive type is set to $CPICReceiveAndWait (the default), then the TSD Script application blocks (waits) until data is received. The time limit for this wait is set in the NDF (node definitions file) in your Communications Manager directory.

Note: The Communications Manager default for this value is INFINITE.

See the section on DDFs in the chapter that discusses using CPIC for an in-depth discussion of the proper usage of the DDFs. This command implicitly causes the internal buffer to be flushed. The application can receive both data and conversation status on the same call.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICRequestToSend

Description

Issues a request to send data to the partner application.

Parameters

conv: CONVERSATION EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which you wish to enter Send state.

Return type

INTEGER

Notes

The remote application is notified of the arrival of the request by the reqTSRcvd parameter of one of the CPICSend, CPICSendError, CPICConfirm, or CPICTestRequestToSendReceived commands.

The value is $CPICReqToSendReceived.

After the remote application enters Receive state (by issuing the appropriate commands), the local application is in Send or Send-Pending state. The remote LU retains only one request to send at a time per conversation. Additional notifications are discarded until the remote application is notified during a CPIC call.

Note that this means that an application may issue more CPICRequestToSend calls than may be indicated to the remote application.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSend

Description

Sends data to the partner application on the given conversation.

Parameters

conv      : CONVERSATION EXPRESSION 
DDFName   : STRING EXPRESSION 
buffer    : ANY EXPRESSION 
reqTSRcvd : INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation over which the data is sent.
DDFName The DDF to be used in extracting the values from the buffer and building a block of bytes to be transmitted.
buffer The TSD Script variable containing the data to be sent. The type of this variable may be a TSD Script simple type (INTEGER, REAL, BOOLEAN, TIME, DATE) or a user-defined record type.
reqTSRcvd Indicates whether or not the partner has requested to send data.

This variable has the values:

  • $CPICRequestToSendReceived means the partner has issued a CPICRequestToSend. This is a request that the local application enter Receive state.
  • $CPICRequestToSendNotReceived means the partner has not issued a CPICRequestToSend. The local application is free to remain in Send state.

Return type

INTEGER

Notes

The local LU stores the data to be sent to the remote LU until there is a sufficient amount for transmission, or until the application forces a flush (either explicitly or implicitly). The amount of data sufficient for transmission depends on the characteristics of the session allocated to support the conversation.

When reqTSRcvd indicates $CPICReqToSendReceived, the remote application is asking that the local application enter Receive state. If you often use CPICSend in conjunction with CPICFlush, CPICConfirm, or CPICPrepareToReceive, investigate the usage of CPICSetSendType. Using this set command is likely to be more efficient.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSendError

Description

Informs the remote application that the local application detected an error during the conversation.

Parameters

conv      : CONVERSATION EXPRESSION 
reqTSRcvd : INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation on which to indicate the error.
reqTScvd Indicates whether or not the partner has requested to send data.

This variable has the values:

  • $CPICRequestToSendReceived means the partner has issued a CPICRequestToSend command. This is a request that the local application enter Receive state.
  • $CPICRequestToSendNotReceived means the partner has not issued a CPICRequestToSend command. The local application is free to remain in Send state.

Return type

INTEGER

Notes

The local LU may delay sending the error notification right away. If so, the notification is buffered until there is a sufficient amount of data for transmission, or until the local application forces a flush, either explicitly or implicitly. To make sure that the partner application receives the error notification right away, the local application can issue a CPICFlush.

The local application enters Send state when issuing this call from Receive, Confirm, Confirm-Send, Confirm-Deallocate, or Send-Pending state. When this call is issued from Send state, no state change occurs.

See also

CPICSetErrorDirection

CPICSetConvSecurityPassword

Description

Sets the security password to be sent to the partner.

Parameters

conv             : CONVERSATION EXPRESSION 
securityPassword : STRING EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which you want to set the password .
securityPassword The new security password. The partner LU uses this and the security user ID to verify the requestor identity.

Return type

INTEGER

Notes

This call can only be made when the conversation security type is $CPICSecurityProgram. This call should be made after CPICInitialize and before CPICAllocate.

The password is set to a default characteristic (set in the CPIC Side Information entry) at initialization time.

Specification of an invalid password is not detected on this call. It is detected by the partner LU when it receives the allocation request. The local application receives an indication of the error on a subsequent CPIC call.

See also

CPICSetConvSecurityType

Description

Sets the security type for the conversation.

Parameters

conv             : CONVERSATION EXPRESSION 
convSecurityType : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for which you want to set the security type.
convSecurityType The INTEGER indicating the type of security. The TSD Script system constants are:
  • $CPICSecurityNone
  • $CPICSecuritySame
  • $CPICSecurityProgram

Return type

INTEGER

Notes

During CPICInitialize processing, the security type is set to a default value (specified in the CPIC Side Information entry).

For security type of $CPICSecurityNone, the allocation request is sent to the partner LU with no security information.

For security type of $CPICSecuritySame, the allocation request contains the same level of access security information (either none or the user ID) as that used to start the application, provided the partner LU accepta already-verified security information. If the partner does not accept already-verified security information, the allocation request contains no security information.

For security type of $CPICSecurityProgram, the allocation request contains the user ID and password from the corresponding conversation attributes, provided the partner accepts security information from the local LU.

If the TSD Script application sets the security type to $CPICSecurityProgram, it may then call CPICSetConvSecurityPassword and CPICSetConvSecurityUserID.

If the TSD Script application does not set the security type to $CPICSecurityProgram, the values is taken from the CPIC side information entry.

See also

CPICSetConvSecurityUserID

Description

Sets the security user ID for the conversation. This user ID is needed for conversations with security type of $CPICSecurityProgram.

Parameters

conv           : CONVERSATION EXPRESSION 
securityUserID : STRING EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which the security user ID is set.
securityUserID The security user ID. The partner LU uses this and the security password to verify requestor identity.

Return type

INTEGER

Notes

The initial value for the user ID comes from the CPIC Side Information entry during processing of CPICInitialize.
Specification of an invalid security user ID is not detected on this call. The partner LU detects it when it receives the allocation request. The local application receives the notification on a subsequent CPIC call.

See also

CPICSetConvType

Description

Sets the conversation type.

Parameters

conv     : CONVERSATION PARAMETER 
convType : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for which you want to change the conversation type.
convType An integer indicating the conversation type. The TSD Script system constants are:
  • $CPICBasicConversation
  • $CPICMappedConversation

Return type

INTEGER

Notes

During processing of CPICInitialize, the conversation type is set to $CPICMappedConversation. Your application needs to call this function after CPICInitialize to change the type to $CPICBasicConversation. Basic conversations should be regarded as an advanced programming technique.

Example

See the code segment for CPICAccept for a complete example.

CPICSetDeallocateType

Description

Sets the type of deallocation processing to be performed.

Parameters

conv           : CONVERSATION EXPRESSION 
deallocateType : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for which the deallocate type is being set
deallocateType An integer indicating the desired deallocate type. The TSD Script system constants are:
  • $CPICDeallocateSyncLevel
  • $CPICDeallocateFlush
  • $CPICDeallocateConfirm
  • $CPICDeallocateAbend

Return type

INTEGER

Notes

The deallocate type attribute is used by CPIC when you call the CPICDeallocate function.

If a successful reply is received, the conversation is deallocated normally. If an unsuccessful reply is received, the state of the conversation is determined by the return code.

Note that the type of $CPICDeallocateConfirm can only be used when the sync level is $CPICConfirm.

See also

CPICSetErrorDirection

Description

Sets the error direction attribute for a conversation.

Parameters

conv           : CONVERSATION EXPRESSION 
errorDirection : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for which to set the error direction.
errorDirection An integer indicating the direction of the data flow in which the error was detected. The TSD Script system constants are $CPICReceiveError and $CPICSendError.

Return type

INTEGER

Notes

A value of $CPICReceiveError indicates that the local application detected an error in the data it received from the partner. When the local application issues CPICSendError, the remote application receives a return code of -22 (CM_PROGRAM_ERROR_PURGING). A value of $CPICSendError indicates that the local application encountered a problem while preparing data to be sent to the partner. When the local application issues CPICSendError, the remote application receives a return code of -21 (CM_PROGRAM_ERROR_NO_TRUNC).

This error direction attribute is only used when the application is in Send-Pending state ( the only time when it is unclear as to whether it is a receive error or a send error). A application is in the Send-Pending state after a CPICReceive in which both data and a status of $CPICSendReceived were received. The error direction defaults to $CPICReceiveError.
Once the error direction is changed, the new value remains in effect until the application changes it again.

See also

CPICSendError

CPICSetModeName

Description

Sets the mode name to be used for the conversation.

Parameters

conv     : CONVERSATION EXPRESSION 
modeName : STRING EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for which you wish to set the mode name
modeName The mode name to use for the conversation. The mode name specifies network properties for the session carrying the conversation. These network properties include class of service and whether data is to be enciphered.

Return type

INTEGER

Notes

An invalid mode name is not detected on this call. The subsequent CPICAllocate returns an error.

See also

CPICSetPartnerLUName

Description

Sets the partner LU name for the conversation.

Parameters

conv          : CONVERSATION EXPRESSION 
partnerLUName : STRING EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which the partner LU name is changed
partnerLUName The new partner LU name for the conversation. This is the name of the LU where the remote application is located. This LU name is any name by which the local LU knows the remote LU for purposes of allocating a conversation.

Return type

INTEGER

Notes

This call should be issued after CPICInitialize but before CPICAllocate. Issuing this call does not change the information in the CPIC Side Information entry.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSetPrepareToReceiveType

Description

Sets the attribute to be used when CPICPrepareToReceive is called.

Parameters

conv          : CONVERSATION EXPRESSION 
prepToRcvType : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which the prepare to receive type is set.
prepToRcvType An integer indicating the type of prepare to receive processing to be performed. The TSD Script system constants are $CPICPrepToReceiveSyncLevel, $CPICPrepToReceiveFlush, and $CPICPrepToReceiveConfirm.

Return type

INTEGER

Notes

For $CPICPrepToReceiveFlush, the buffer is flushed and the application enters Receive state.

For $CPICPrepToReceiveConfirm, a confirmation request is sent. If successful, the application enters Receive state. If unsuccessful, the state of the conversation is determined by the return code.

For $CPICPrepToReceiveSyncLevel, the processing depends on the sync level. If it is $CPICNone, the actions are the same as for $CPICPrepToReceiveFlush.

If it is $CPICConfirm, processing is the same as for $CPICPrepToReceiveConfirm.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSetReceiveType

Description

Sets the type of receive operation to be performed.

Parameters

conv     : CONVERSATION EXPRESSION 
rcvType  : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which the receive type is changed
rcvType An integer indicating the type of receive processing. The TSD Script system constants are $CPICReceiveAndWait and $CPICReceiveImmediate.

Return type

INTEGER

Notes

This function may be called anytime after the CPICInitialize (for the initiator of the conversation) or CPICAccept (for the receiver of the conversation).

A value of $CPICReceiveAndWait means that a call to the CPICReceive function waits until information has arrived. $CPICReceiveImmediate means that the CPICReceive function receives any data that is available, but does not wait for any more information.

See also

CPICReceive

CPICSetReturnControl

Description

Set the return control attribute for the conversation. This is used on a call to CPICAllocate.

Parameters

conv          : CONVERSATION EXPRESSION 
returnControl : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which the return control is changed
returnControl An integer indicating when the TSD Script application regains control on the call to CPICAllocate. The TSD Script system constants are $CPICWhenSessionAllocated and $CPICImmediate.

Return type

INTEGER

Notes

For $CPICWhenSessionAllocated, the TSD Script application waits until the session is allocated. For $CPICImmediate, the session is only allocated if a free session is immediately available. An allocation error resulting from the local LU's failure to obtain a session for the conversation is reported on the CPICAllocate call. A rejection from the partner LU is reported on a subsequent conversation call.

See also

CPICAllocate

CPICSetSendType

Description

Sets the send type attribute for the conversation.

Parameters

conv     : CONVERSATION EXPRESSION 
sendType : INTEGER EXPRESSION 

Parameter notes

Parameters Description
conv The conversation for which the send type is changed.
sendType An integer indicating the actions to be taken on every call to CPICSend. The TSD Script system constants are:
  • $CPICBufferData
  • $CPICSendAndFlush
  • $CPICSendAndConfirm
  • $CPICSendAndPrepToReceive
  • $CPICSendAndDeallocate

Return type

INTEGER

Notes

With $CPICBufferData (the default), no additional actions is needed besides sending data. Also, the data may be stored internally until an amount sufficient for transmission has accumulated through multiple CPICSend calls.

$CPICSendAndFlush indicates a flush operation is carried out after each CPICSend.

$CPICSendAndConfirm indicates a confirmation request is sent after each CPICSend.

$CPICSendAndPrepToReceive indicates that the local application gives send control to the remote application on the call to CPICSend.

$CPICSendAndDeallocate indicates that the conversation is deallocated after the data is sent.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSetSideInfo

Description

Adds or replaces a CPIC Side Information entry in the CPIC Side Information table.

Parameters

keylock          : STRING EXPRESSION 
symDestName      : STRING EXPRESSION 
partnerLUName    : STRING EXPRESSION 
TPNameType       : INTEGER EXPRESSION 
TPName           : STRING EXPRESSION 
modeName         : STRING EXPRESSION 
convSecurityType : INTEGER EXPRESSION 
securityUserID   : STRING EXPRESSION 
securityPassword : STRING EXPRESSION 

Parameter notes

Parameter Description
keylock The master or service key, when the Communications Manager keylock feature has been secured Pad this key with blanks to eight characters if necessary.
symDestName The SDN of the entry. This value is used as the key into the table. If it is found in the table, the values are updated. Otherwise, a new entry is made in the table.
partnerLUName The LU name of the remote application.
TPNameType An integer indicating the type of TP. The TSD Script system constants are $CPICApplicationTP and $CPICSNAServiceTP.
TPName The name of the transaction application which is the partner to this conversation. If you specified $CPICSNAServiceTP, you must specify the name in the form '\xhhaaa' where hh is treated as a hexadecimal value and the other characters are treated as alphanumeric.
modeName The mode name to be used for the conversation.
convSecurityType An integer indicating the type of security for any conversation allocated with this side info entry. The TSD Script system constants are $CPICSecurityNone, $CPICSecuritySame, $CPICSecurityProgram.
securityUserID The user ID to be sent to the partner for verification. This value must be set if the convSecurityType is $CPICSecurityProgram.
securityPassword The password to be sent to the partner during security verification. This value is only needed if convSecurityType is $CPICSecurityProgram.

Return type

INTEGER

Notes

This call does not change the Communications Manager configuration file. Therefore, the modifications made to the Side Information entry exist only as long as the local application is executing.

The string values passed to this function are not checked for validity on this call.

This function does not affect any active conversations. While Communications Manager is updating the CPIC Side Information entry, any other application's call to change or extract the entry information is suspended until this function is completed. This includes another application's call to CPICInitialize.

See also

CPICSetSyncLevel

Description

Sets the sync level attribute for a conversation.

Parameters

conv      : CONVERSATION EXPRESSION 
SYNCLEVEL : INTEGER EXPRESSION 

Parameter notes

Parameter Description
conv The conversation handle for which the sync level is changed.
SYNCLEVEL An integer indicating the synchronization level to use for the conversation. The TSD Script system constants are $CPICNone and $CPICConfirm.

Return type

INTEGER

Notes

$CPICNone means that the applications do not perform any confirmation processing on this conversation. $CPICConfirm means that the applications can perform confirmation processing. The sync level may only be set after CPICInitialize, but before CPICAllocate. Only the initiator of a conversation can use this function.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSetTPName

Description

Sets the TP name for the conversation. This is given to the partner LU as the name of the transaction application to be executed as the remote application of the conversation.

Parameters

conv   : CONVERSATION EXPRESSION 
TPName : STRING EXPRESSION 

Parameter notes

Parameter Description
conv The conversation for which the TP name is changed.
TPName The new TP name for the conversation. Note that this must be an application TP, not an SNA service TP.

Return type

INTEGER

Notes

This function can only be used to set application TP names, not SNA service TP names.

Example

See the code segment for CPICAccept for a complete example.

See also

CPICSetSideInfo

CPICTestRequestToSendReceived

Description

Checks if a request to send has been issued by the partner application.

Parameters

conv      : CONVERSATION EXPRESSION 
reqTSRcvd : INTEGER PARAMETER 

Parameter notes

Parameter Description
conv The conversation to be tested.
reqTSRcvd Contains an integer indicating whether a request to send has been received from the partner. TSD Script system constants are $CPICReqToSendReceived and $CPICReqToSendNotReceived.

Return type

INTEGER

Notes

When the local LU receives the request notification, it retains the notification until the local application issues a call with the reqTSRcvd parameter. Only one notification is retained at a time, so additional requests are discarded until the local application is notified.

See also


Tivoli Service Desk 6.0 Developer's Toolkit Legacy APIs Guide

Back to Table of Contents

Copyright