[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPCVD - Convert Data

GPCVD (datatype, env, origin, datalen, idata, odata)

Purpose

Use GPCVD to convert data that is valid in one environment to data that is valid in another environment.

The differences in data in different environments could be:

  • character encoding can be EBCDIC or ASCII

  • floating-point format can be IBM single precision or IEEE single precision.

  • the byte order of data can be swapped.

    • You need to convert data when:

  • an application process is communicating with another application process and the data the one application process receives from the other application process is not in a form that it recognizes. Likewise, you need to convert data when an application process wants to send data to another application process in a form that the receiving application process recognizes.

  • an application is directing workstation-dependent output (WDO) to a workstation existing in a different environment.
    • When using GPCVD for converting communication data between application processes:

  • The environment descriptor is the descriptor of the environment of the application process communicating with your application process. Your application process has either received data from or is sending data to that application process. An application process can inquire its environment descriptor by issuing the Inquire Shell Identifier (GPQSH) subroutine. An application process can pass its environment descriptor to another application process by issuing the Send Broadcast Message (GPSBMS) subroutine or the Send Private Message (GPSPMS) subroutine.

  • The origin parameter identifies whether the data to be converted originated in your application process doing the conversion (1=LOCAL_DATA ) or in the application process you are communicating with (2=EXTERNAL_DATA )

    • When using GPCVD for converting an application's workstation-dependent output (WDO) data to a form recognized by the environment of the workstation to which it is directed:

  • The environment descriptor is the descriptor of the environment of the workstation to which the WDO is directed. You can inquire the environment descriptor of the workstation by issuing the Inquire Nucleus Environment (GPQNCE) subroutine. Specify a type parameter of 2=ENVIRONMENT_DESCRIPTOR and a nucleus identifier (ncid) of the nucleus where the workstation was created. If the workstation was opened using the Open Workstation (GPOPWS) subroutine, then use a nucleus identifier of one.

  • You should set the origin parameter to 1=LOCAL_DATA

    • The conversion of string data is done using the current text character set defined in the graPHIGS API state list (see the Set Text Character Set [GPTXCS] subroutine [page GPTXCS - Set Text Character Set] ) The one exception to this is if your application is running locally within the 6090, the graPHIGS API uses the IBM defined character set 1 for the conversion.

    Parameters

    datatype -- specified by user, fullword integer

    Type of data that is being converted (1=CHARACTER_STRING, 2=FLOATS, 3=INTEGERS,4=DATA_RECORD ) 
     
                    ---------------------
     Data Record  0 | Number of integers|  Fullword integer
       Format       |       or 0        |
                    |-------------------|
                  4 | Number of floats  |  Fullword integer
                    |       or 0        |
                    |-------------------|
                  8 | Number of strings |  Fullword integer
                    |       or 0        |
                    |-------------------|
                    |     Integers      |
                    |-------------------|
                    |      Floats       |
                    |-------------------|
                    |      Strings      |
                    ---------------------

    Note:

    The first byte of a data record string is the length of the string.

    env -- specified by user, 4-byte character string

    Environment descriptor.

    origin -- specified by user, fullword integer

    Origin of the data to be converted (1=LOCAL_DATA, 2=EXTERNAL_DATA )

    datalen -- specified by user, fullword integer (>0)

    Length in bytes of the data being converted. This also equals the length of the area to return the converted data.

    idata -- specified by user, variable data

    Data to be converted.

    odata -- returned by the graPHIGS API, variable data

    The converted data.

    Note: The input area (idata) and the output area (odata) may be the same area.

    Error Codes

    146
    FIELD IN INPUT DEVICE DATA RECORD IN ERROR
    177
    ORIGIN PARAMETER IS INVALID
    178
    DATATYPE PARAMETER IS INVALID
    179
    ENVIRONMENT DESCRIPTOR IS INVALID
    509
    DATA LENGTH VALUE < ZERO OR REQUIRED LENGTH

    Related Subroutines

    GPES
    Escape
    GPQNCE
    Inquire Nucleus Environment
    GPQSH
    Inquire Shell Identifier
    GPSBMS
    Send Broadcast Message
    GPSPMS
    Send Private Message
    GPWDO
    Workstation-Dependent Output

    RCP code

    201330959 (X'0C00110F')

    [ Previous | Next | Contents | Glossary | Home | Search ]