_SETCCSID()--Set IBM PASE for i CCSID

 #include <as400_protos.h>

 int _SETCCSID(int  ccsid);  

Note: This function can only be used in an IBM^® i PASE program. See the IBM PASE for i topic collection for more information about creating IBM PASE for i programs.

The _SETCCSID() function returns the previous value of the IBM PASE for i Coded Character Set Identifier (CCSID) and optionally sets a new IBM PASE for i CCSID.

Parameters

ccsid

(Input) Specifies the new IBM PASE for i CCSID value, or -1 to retrieve the current IBM PASE for i CCSID without changing it. An IBM PASE for i CCSID must be either a single-byte ASCII encoding that the ILE version of iconv can convert to and from the job default CCSID, or 1208 for UTF-8 encoding.

Authorities

_SETCCSID requires no authority.

Return Value

_SETCCSID returns either the original IBM PASE for i CCSID (before it was changed), or -1 if an error occurred and the IBM PASE for i CCSID was left unchanged.

Error Conditions

The only error condition that causes a function result of -1 is that the new ccsid cannot be converted to or from the IBM i job default CCSID.

Usage Notes

1. The initial IBM PASE for i CCSID value is specified as a parameter on the Qp2RunPase API. The IBM PASE for i CCSID has two primary uses:
   
   
   • It is used to set the the CCSID attribute of any bytestream file created in the Integrate File System by an IBM PASE for i program.
     
     
   • It is used by IBM PASE for i runtime functions to convert character arguments and results between the IBM PASE for i CCSID and whatever encoding is required by the IBM i service used to implement the function.
     
   
   
2. The IBM PASE for i CCSID should generally be the CCSID equivalent of the code set for the current locale. See IBM PASE for i Locales to determine what locales are supported by IBM PASE for i.
   
   
3. Character arguments and results for IBM PASE for i runtime functions that use IBM i services are almost always automatically converted using the IBM PASE for i CCSID. For example, the name of a bytestream file passed to the IBM PASE for i open function is converted from the IBM PASE for i CCSID to the internal encoding required by the IBM i Integrated File System.
   
   
4. Any data an IBM PASE for i program writes to or reads from a file descriptor for an open bytestream file, socket, FIFO, or pipe is generally not converted. The only exception is for the initial file descriptors 0, 1, and 2 provided when the Qp2RunPase API is called to start an IBM PASE for i program, which default to converting file data between the IBM PASE for i CCSID and the job default CCSID (see Qp2RunPase()--Run an IBM PASE for i Program for more information).
   
   
5. Other than special support for file descriptors 0, 1, and 2, IBM PASE for i runtime does no CCSID conversion of file data. This differs from ILE runtime, which does CCSID conversion between the file CCSID and job default CCSID for any file opened in text mode. IBM PASE for i runtime sets the CCSID attribute of any file it creates to the IBM PASE for i CCSID, so an ILE program that uses text mode to open an ASCII file created by an IBM PASE for i program can read and write EBCDIC data.
   
   
6. The IBM PASE for i runtime functions cstoccsid and ccsidtocs convert between AIX^® Character Set names and CCSID values.

Related Information

• Qp2RunPase()--Run an IBM PASE for i Program

[ Back to top | IBM PASE for i APIs | APIs by category ]