Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer Guide
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:
Accepts an incoming CPIC or APPC conversation.
conv: CONVERSATION
Parameter | Description |
conv | Conversation handle to initialize with the incoming conversation characteristics |
INTEGER
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.
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;
Establishes a basic or mapped conversation with a partner application.
conv: CONVERSATION EXPRESSION
Parameter | Description |
conv | The conversation that has been initialized and is to be allocated |
INTEGER
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.
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.
See the code segment for CPICAccept for a complete example.
Requests confirmation (on receipt of data) from the partner application, then waits for a reply.
conv : CONVERSATION EXPRESSION reqTSRcvd: INTEGER PARAMETER
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:
|
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Replies to a confirmation request by the partner.
conv: CONVERSATION EXPRESSION
Parameter | Description |
conv | The conversation that has been initialized and is to be allocated |
INTEGER
This function should only be called when the partner has requested confirmation.
See the code segment for CPICAccept for a complete example.
Ends a conversation and frees the resources dedicated to that conversation.
conv: CONVERSATION EXPRESSION
Parameter | Description |
conv | The conversation that has been initialized and is to be allocated |
INTEGER
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:
See the code segment for CPICAccept for a complete example.
Deletes the designated CPIC side information entry.
keylock : STRING EXPRESSION symDestName: STRING EXPRESSION
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 |
INTEGER
If the return code is anything other than one, the entry has not been deleted.
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.
Obtains the security type for the conversation.
conv : CONVERSATION convSecurityType: INTEGER PARAMETER
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:
|
INTEGER
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.
Obtains the security user ID associated with a conversation.
conv : CONVERSATION EXPRESSION securityUserID: STRING PARAMETER
Parameter | Description |
conv | The conversation handle for the security user ID |
securityUserID | Contains the ID of the user with access to the conversation |
INTEGER
The security user ID is set to a default value on the call to CPICInitialize. It can be changed with a call to CPICSetConvSecurityUserID.
Obtains the state of the given conversation.
conv : CONVERSATION EXPRESSION state: INTEGER PARAMETER
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:
|
INTEGER
Obtains the type of the given conversation.
conv : CONVERSATION PARAMETER convType : INTEGER PARAMETER
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:
|
INTEGER
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.
Obtains the mode name for the given conversation.
conv : CONVERSATION EXPRESSION modeName : STRING PARAMETER
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. |
INTEGER
Obtains the partner application's LU name.
conv : CONVERSATION EXPRESSION partnerLUName : STRING PARAMETER
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 |
INTEGER
Obtains the parameters for the indicated SDN.
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 | 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. |
INTEGER
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.
Obtains the current sync level for the conversation.
conv : CONVERSATION EXPRESSION SYNCLEVEL : INTEGER PARAMETER
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:
INTEGER
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.
Causes the Communications Manager to send any data in the internal buffers.
conv: CONVERSATION EXPRESSION
Parameter | Description |
conv | The conversation handle for flushed data |
INTEGER
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.
Configures and prepares internal resources for a conversation. Many characteristics are set to default values and associated with the specified conversation handle.
conv : CONVERSATION PARAMETER symDestName: STRING EXPRESSION
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. |
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Changes the local end of the conversation from Send state to Receive state, as a preparation to receive data.
conv: CONVERSATION EXPRESSION
Parameter | Description |
conv | The handle identifying the conversation to be put in Receive state. |
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Receives incoming data from the specified conversation.
conv : CONVERSATION EXPRESSION DDFName : STRING EXPRESSION buffer : ANY PARAMETER dataReceived : INTEGER PARAMETER statusReceived: INTEGER PARAMETER reqTSRcvd : INTEGER PARAMETER
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:
|
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.
|
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Issues a request to send data to the partner application.
conv: CONVERSATION EXPRESSION
Parameter | Description |
conv | The conversation for which you wish to enter Send state. |
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Sends data to the partner application on the given conversation.
conv : CONVERSATION EXPRESSION DDFName : STRING EXPRESSION buffer : ANY EXPRESSION reqTSRcvd : INTEGER PARAMETER
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:
|
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Informs the remote application that the local application detected an error during the conversation.
conv : CONVERSATION EXPRESSION reqTSRcvd : INTEGER PARAMETER
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:
|
INTEGER
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.
Sets the security password to be sent to the partner.
conv : CONVERSATION EXPRESSION securityPassword : STRING EXPRESSION
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. |
INTEGER
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.
Sets the security type for the conversation.
conv : CONVERSATION EXPRESSION convSecurityType : INTEGER EXPRESSION
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:
|
INTEGER
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.
Sets the security user ID for the conversation. This user ID is needed for conversations with security type of $CPICSecurityProgram.
conv : CONVERSATION EXPRESSION securityUserID : STRING EXPRESSION
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. |
INTEGER
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.
Sets the conversation type.
conv : CONVERSATION PARAMETER convType : INTEGER EXPRESSION
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:
|
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Sets the type of deallocation processing to be performed.
conv : CONVERSATION EXPRESSION deallocateType : INTEGER EXPRESSION
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:
|
INTEGER
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.
Sets the error direction attribute for a conversation.
conv : CONVERSATION EXPRESSION errorDirection : INTEGER EXPRESSION
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. |
INTEGER
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.
Sets the mode name to be used for the conversation.
conv : CONVERSATION EXPRESSION modeName : STRING EXPRESSION
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. |
INTEGER
An invalid mode name is not detected on this call. The subsequent CPICAllocate returns an error.
Sets the partner LU name for the conversation.
conv : CONVERSATION EXPRESSION partnerLUName : STRING EXPRESSION
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. |
INTEGER
This call should be issued after CPICInitialize but before CPICAllocate. Issuing this call does not change the information in the CPIC Side Information entry.
See the code segment for CPICAccept for a complete example.
Sets the attribute to be used when CPICPrepareToReceive is called.
conv : CONVERSATION EXPRESSION prepToRcvType : INTEGER EXPRESSION
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. |
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Sets the type of receive operation to be performed.
conv : CONVERSATION EXPRESSION rcvType : INTEGER EXPRESSION
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. |
INTEGER
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.
Set the return control attribute for the conversation. This is used on a call to CPICAllocate.
conv : CONVERSATION EXPRESSION returnControl : INTEGER EXPRESSION
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. |
INTEGER
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.
Sets the send type attribute for the conversation.
conv : CONVERSATION EXPRESSION sendType : INTEGER EXPRESSION
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:
|
INTEGER
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.
See the code segment for CPICAccept for a complete example.
Adds or replaces a CPIC Side Information entry in the CPIC Side Information table.
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. |
INTEGER
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.
Sets the sync level attribute for a conversation.
conv : CONVERSATION EXPRESSION SYNCLEVEL : INTEGER EXPRESSION
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. |
INTEGER
$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.
See the code segment for CPICAccept for a complete example.
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.
conv : CONVERSATION EXPRESSION TPName : STRING EXPRESSION
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. |
INTEGER
This function can only be used to set application TP names, not SNA service TP names.
See the code segment for CPICAccept for a complete example.
Checks if a request to send has been issued by the partner application.
conv : CONVERSATION EXPRESSION reqTSRcvd : INTEGER PARAMETER
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. |
INTEGER
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.
Tivoli Service Desk 6.0 Developer's Toolkit Legacy APIs Guide