#include <stdlib.h>
Go to the source code of this file.
Data Structures | |
struct | ECI_CONTAINER_INFO |
Container information structure. More... | |
Macros | |
#define | CICSCALL |
#define | ECI_NULL_CHANNELTOKEN (ECI_ChannelToken_t) NULL |
#define | ECI_CONTAINERNAME_LENGTH 16 |
#define | ECI_CHANNELNAME_LENGTH 16 |
#define | ECI_NO_ERROR 0 |
#define | ECI_ERR_INVALID_DATA_LENGTH -1 |
#define | ECI_ERR_SYSTEM_ERROR -9 |
#define | ECI_ERR_INVALID_CHANNEL -50 |
#define | ECI_ERR_INVALID_NAME -51 |
#define | ECI_ERR_NULLCHANNELPTR -52 |
#define | ECI_ERR_CHANNELLOCKFAIL -53 |
#define | ECI_ERR_ENDOFCONTAINERS -54 |
#define | ECI_ERR_NULLINFOPTR -55 |
#define | ECI_ERR_INVALID_TYPE -56 |
#define | ECI_ERR_CONTAINER_NOTFOUND -58 |
#define | ECI_ERR_CONTAINER_EXISTS -59 |
#define | ECI_ERR_COMMAREA_AND_CHANNEL -60 |
#define | ECI_ERR_NULLPTR -109 |
#define | ECI_ERR_MEMORY_SHORTAGE -111 |
#define | ECI_ERR_LOCKFAIL -121 |
Typedefs | |
typedef struct _ECI_Channel_t * | ECI_ChannelToken_t |
Enumerations | |
enum | ECI_CONTAINER_TYPE { ECI_BIT = 0x01, ECI_CHAR = 0x02 } |
Functions | |
int | ECI_createChannel (const char *name, ECI_ChannelToken_t *tokPtr) |
int | ECI_deleteChannel (ECI_ChannelToken_t *tokPtr) |
int | ECI_deleteAllChannels () |
int | ECI_getChannelName (ECI_ChannelToken_t chanTok, char *nameBuffer) |
int | ECI_getFirstContainer (ECI_ChannelToken_t chanTok, ECI_CONTAINER_INFO *infoPtr) |
int | ECI_getNextContainer (ECI_ChannelToken_t chanTok, ECI_CONTAINER_INFO *infoPtr) |
int | ECI_createContainer (ECI_ChannelToken_t chanTok, const char *name, ECI_CONTAINER_TYPE type, const int ccsid, const void *data, size_t dataLength) |
int | ECI_deleteContainer (ECI_ChannelToken_t chanTok, const char *name) |
int | ECI_getContainerInfo (ECI_ChannelToken_t chanTok, const char *name, ECI_CONTAINER_INFO *infoPtr) |
int | ECI_getContainerData (ECI_ChannelToken_t chanTok, const char *name, void *buffer, size_t length, size_t offset, size_t *bytesReadPtr) |
int | ECI_setContainerData (ECI_ChannelToken_t chanTok, const char *name, const void *data, size_t dataLength) |
Detailed Description
Defines functions and typedefs for creating and using channels and containers.
Definition in file eci_channel.h.
Macro Definition Documentation
#define CICSCALL |
Definition at line 57 of file eci_channel.h.
#define ECI_CHANNELNAME_LENGTH 16 |
Definition at line 113 of file eci_channel.h.
#define ECI_CONTAINERNAME_LENGTH 16 |
Definition at line 95 of file eci_channel.h.
#define ECI_ERR_CHANNELLOCKFAIL -53 |
Unable to create a lock for the channel.
Definition at line 487 of file eci_channel.h.
#define ECI_ERR_COMMAREA_AND_CHANNEL -60 |
Both a COMMAREA and a channel are specified.
Definition at line 505 of file eci_channel.h.
#define ECI_ERR_CONTAINER_EXISTS -59 |
A container with the same name already exists in the channel.
Definition at line 502 of file eci_channel.h.
#define ECI_ERR_CONTAINER_NOTFOUND -58 |
The specified container does not exist in the channel.
Definition at line 499 of file eci_channel.h.
#define ECI_ERR_ENDOFCONTAINERS -54 |
There are no more containers in the channel.
Definition at line 490 of file eci_channel.h.
#define ECI_ERR_INVALID_CHANNEL -50 |
The channel token is not valid.
Definition at line 478 of file eci_channel.h.
#define ECI_ERR_INVALID_DATA_LENGTH -1 |
Bad data length.
Definition at line 472 of file eci_channel.h.
#define ECI_ERR_INVALID_NAME -51 |
The specified name is not valid.
Definition at line 481 of file eci_channel.h.
#define ECI_ERR_INVALID_TYPE -56 |
The container type is not valid.
Definition at line 496 of file eci_channel.h.
#define ECI_ERR_LOCKFAIL -121 |
Internal error during lock creation.
Definition at line 515 of file eci_channel.h.
#define ECI_ERR_MEMORY_SHORTAGE -111 |
The API was unable to allocate sufficient memory to complete the operation.
Definition at line 512 of file eci_channel.h.
#define ECI_ERR_NULLCHANNELPTR -52 |
The channel token pointer is NULL.
Definition at line 484 of file eci_channel.h.
#define ECI_ERR_NULLINFOPTR -55 |
The ECI_CONTAINER_INFO pointer is NULL.
Definition at line 493 of file eci_channel.h.
#define ECI_ERR_NULLPTR -109 |
A pointer parameter was NULL.
Definition at line 508 of file eci_channel.h.
#define ECI_ERR_SYSTEM_ERROR -9 |
An internal system error has occurred.
Definition at line 475 of file eci_channel.h.
#define ECI_NO_ERROR 0 |
No error.
Definition at line 469 of file eci_channel.h.
#define ECI_NULL_CHANNELTOKEN (ECI_ChannelToken_t) NULL |
Null channel token.
Definition at line 77 of file eci_channel.h.
Typedef Documentation
typedef struct _ECI_Channel_t* ECI_ChannelToken_t |
Represents a channel object.
Definition at line 74 of file eci_channel.h.
Enumeration Type Documentation
enum ECI_CONTAINER_TYPE |
Container type enumeration.
Definition at line 81 of file eci_channel.h.
Function Documentation
int ECI_createChannel | ( | const char * | name, |
ECI_ChannelToken_t * | tokPtr | ||
) |
Creates a new channel with the specified name and provides the caller with a channel token for use with other channel related functions.
Channel names are up to ECI_CHANNELNAME_LENGTH characters in length and are case sensitive. Allowable characters are:
- Uppercase characters A-Z
- Lowercase characters a-z
- Digits 0-9
- Special characters < > $ @ # / % & ? ! : | " = ' ; . - _
It is not possible to modify a channel name after creation.
ECI_CHAR data always has an associated coded character set identifier (CCSID) which describes the encoding of the data.
When a channel is created, a default CCSID is set based upon the encoding of the current locale of the application. If no mapping exists for the current locale, the CCSID for US-ASCII is used.
The default CCSID for a channel is replaced by the CCSID of the first container of type ECI_CHAR to be added to the channel.
Adding subsequent containers of any type or CCSID has no effect upon the channel CCSID and it cannot be changed explicitly.
- Parameters
-
[in] name The name for the new channel. [out] tokPtr Pointer to a channel token. If the call is successful, tokPtr is modified to point at the new channel token.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
- See Also
- ECI_createContainer()
int ECI_createContainer | ( | ECI_ChannelToken_t | chanTok, |
const char * | name, | ||
ECI_CONTAINER_TYPE | type, | ||
const int | ccsid, | ||
const void * | data, | ||
size_t | dataLength | ||
) |
Creates a new container in the channel associated with the specified channel token.
Container names are up to ECI_CONTAINERNAME_LENGTH characters in length and are case sensitive. Allowable characters are:
- Uppercase characters A-Z
- Lowercase characters a-z
- Digits 0-9
- Special characters < > $ @ # / % & ? ! : | " = ' ; . - _
It is not possible to modify a container name or type after creation.
ECI_CHAR data always has an associated coded character set identifier (CCSID) which describes the encoding of the data.
When a container is created of type ECI_CHAR with a CCSID of zero, the container CCSID is set to the channel CCSID.
The default CCSID for a channel is replaced by the CCSID of the first container of type ECI_CHAR to be added to the channel.
Adding subsequent containers of any type or CCSID has no effect upon the channel CCSID and it cannot be changed explicitly.
- Parameters
-
[in] chanTok A channel token representing the channel to which the new container is added. [in] name A pointer to a null terminated character string, up to ECI_CHANNELNAME_LENGTH bytes in length (excluding null terminator), to be used as the name for the new container. [in] type The type of container to be created: [in] ccsid A CCSID value that specifies the encoding of the data when the container type is ECI_CHAR. The CCSID is ignored when the container type is ECI_BIT. Set to zero when container type is ECI_CHAR to use the channel CCSID. [in] data A pointer to the data to be copied into the new container. [in] dataLength The number of bytes of data to be copied into the new container.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
- See Also
- ECI_createChannel()
int ECI_deleteAllChannels | ( | ) |
Deletes all existing channels and associated containers.
This function can be used by the API program under normal circumstances, or in the event of a severe error, enabling some form of controlled shutdown when references to channel tokens might have been lost.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int ECI_deleteChannel | ( | ECI_ChannelToken_t * | tokPtr | ) |
Deletes the channel represented by the specified channel token and associated containers.
Following a successful call, any copy of the channel token or ECI_CONTAINER_INFO variable representing an associated container is invalidated.
- Parameters
-
[in,out] tokPtr Pointer to a channel token. If the call is successful, tokPtr is modified to point to ECI_NULL_CHANNELTOKEN.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int ECI_deleteContainer | ( | ECI_ChannelToken_t | chanTok, |
const char * | name | ||
) |
Deletes the named container from the channel associated with the specified channel token.
- Parameters
-
[in] chanTok A channel token representing the channel from which the named container is deleted. [in] name A pointer to a null terminated character string, up to ECI_CHANNELNAME_LENGTH bytes in length (excluding null terminator), representing the name of the container to be deleted.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int ECI_getChannelName | ( | ECI_ChannelToken_t | chanTok, |
char * | nameBuffer | ||
) |
Gets the name of the channel represented by the specified channel token.
Following a successful call, nameBuffer contains a null terminated string up to ECI_CHANNELNAME_LENGTH bytes in length (excluding null terminator). The channel name is set using the ECI_createChannel() function.
- Parameters
-
[in] chanTok A channel token representing the channel from which to obtain the name. [out] nameBuffer A pointer to a character buffer at least ECI_CHANNELNAME_LENGTH+1 in length, into which the channel name is copied.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int ECI_getContainerData | ( | ECI_ChannelToken_t | chanTok, |
const char * | name, | ||
void * | buffer, | ||
size_t | length, | ||
size_t | offset, | ||
size_t * | bytesReadPtr | ||
) |
Gets data from the named container in the channel associated with the specified channel token.
Data from the specified container can be copied to the buffer in a single call or iteratively. The size of the application buffer must be at least the number of bytes specified in parameter length
.
- Parameters
-
[in] chanTok A channel token representing the channel from which data for the named container is obtained. [in] name A pointer to a null terminated character string, up to ECI_CHANNELNAME_LENGTH bytes in length (excluding null terminator), representing the name of the container. [out] buffer A pointer to a data buffer into which the data for the named container is copied. [in] length The maximum number of bytes of data to copy into the buffer. [in] offset The number of bytes into the named container data from which the specified number of bytes are copied. [out] bytesReadPtr A pointer to a size_t variable, into which the number of bytes copied is set. This might be less than or equal to the number of bytes requested if the end of the data available is reached. Set to NULL
if this information is not required.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int ECI_getContainerInfo | ( | ECI_ChannelToken_t | chanTok, |
const char * | name, | ||
ECI_CONTAINER_INFO * | infoPtr | ||
) |
Gets information about the named container in the channel associated with the specified channel token.
- Parameters
-
[in] chanTok A channel token representing the channel from which information for the named container is obtained. [in] name A pointer to a null terminated character string, up to ECI_CHANNELNAME_LENGTH bytes in length (excluding null terminator), representing the name of the container. [out] infoPtr A pointer to an ECI_CONTAINER_INFO struct, into which information regarding the named container is copied.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int ECI_getFirstContainer | ( | ECI_ChannelToken_t | chanTok, |
ECI_CONTAINER_INFO * | infoPtr | ||
) |
Gets the first container from the channel represented by the specified channel token.
Functions ECI_getFirstContainer() and ECI_getNextContainer() enable you to iterate over a set of containers within a channel.
Following a successful call, the referenced struct ECI_CONTAINER_INFO contains details of the first container in the channel.
- Parameters
-
[in] chanTok A channel token representing the channel from which to obtain the container. [out] infoPtr A pointer to an ECI_CONTAINER_INFO struct, into which information regarding the first container is copied.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
- See Also
- ECI_getNextContainer()
int ECI_getNextContainer | ( | ECI_ChannelToken_t | chanTok, |
ECI_CONTAINER_INFO * | infoPtr | ||
) |
Gets the next container from the channel represented by the specified channel token.
Functions ECI_getFirstContainer() and ECI_getNextContainer() enable you to iterate over a set of containers within a channel.
Following a successful call, the referenced struct ECI_CONTAINER_INFO contains details of the next container in the channel.
If this call follows a call to the ECI_getFirstContainer() function for the same channel, the container information is set with details of the second container in the channel, if available.
If this call follows a call to the ECI_getNextContainer() function for the same channel, the container information is set with details of the next available container in the channel.
If this call does not follow a call to the ECI_getFirstContainer() or ECI_getNextContainer() function for the same channel, the container information is set with details of the first container in the channel.
- Parameters
-
[in] chanTok A channel token representing the channel from which to obtain the container. [out] infoPtr A pointer to an ECI_CONTAINER_INFO struct, into which information regarding the next container is copied.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
- See Also
- ECI_getFirstContainer()
int ECI_setContainerData | ( | ECI_ChannelToken_t | chanTok, |
const char * | name, | ||
const void * | data, | ||
size_t | dataLength | ||
) |
Copies data into the named container in the channel associated with the specified channel token.
Data from the specified location is copied to the named container. If the container type is ECI_CHAR, the data is assumed to be of the same encoding specified on the ECI_createContainer() call.
- Parameters
-
[in] chanTok A channel token representing the channel into which data for the named container is set. [in] name A pointer to a null terminated character string, up to ECI_CHANNELNAME_LENGTH bytes in length (excluding null terminator), representing the name of the container. [in] data A pointer to the data to be copied into the named container. [in] dataLength The number of bytes of data to copy into the named container. If set to zero, the named container is set to empty.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include