Progress
External Program
Interfaces


Reading and Writing Data

Once you have initialized a MEMPTR variable, you can build a data aggregate (structure) or access an existing structure in the associated memory region using several memory-writing statements and memory-reading functions. Memory-writing statements write values to specified locations in the memory region. Memory-reading functions return values from the specified locations in the memory region. Through an appropriate choice of these statements and functions you can thus copy Progress data types and bit fields to and from MEMPTR variables. You can also copy complete Progress database records to and from MEMPTR variables.

NOTE: Before setting or getting values in a MEMPTR variable, you might want to check the MEMPTR size using the GET-SIZE function. For more information, see the "Initializing and Uninitializing MEMPTR Variables" section.

This is the syntax for the MEMPTR memory-writing statements (except PUT-STRING):

SYNTAX
PUT-datatype ( mptr-name , byte-position ) = expression 

This is the syntax for the MEMPTR memory-reading functions (except GET-STRING and GET-BYTES):

SYNTAX
GET-datatype ( mptr-name , byte-position ) 

Each PUT-datatype statement writes a value (expression) of a certain data type to the memory region associated with the MEMPTR variable mptr-name at the specified byte-position. Each GET-datatype function reads and returns the value of a data type from the memory region associated with the MEMPTR variable mptr-name at the specified byte-position. The byte-position in these statements and functions is specified by an integer expression that starts at one (1).

The PUT-STRING statement and GET-STRING function each allow an additional optional parameter that specifies the number of bytes to write or read in the MEMPTR variable. The GET BYTES function has the same parameter, but it is required for this function.

NOTE: The mptr-name parameter in these statements and functions can reference RAW as well as MEMPTR variables. However, the EPIs that require MEMPTR variables cannot use RAW variables directly. You must convert RAW values to MEMPTR before using them with these EPIs. You can do this using direct assignment between RAW and MEMPTR variables or by using statements and functions such as PUT-BYTES, GET-BYTES, or GET-RAW.

Memory-writing Statements

Progress provides the PUT-datatype statements shown in Table 1–1.

Table 1–1: PUT-datatype Statements
Statement
Description
PUT-BYTE
Writes an integer value to the specified 1-byte location.
PUT-SHORT
Writes an integer value to the specified 2-byte location.
PUT-UNSIGNED-SHORT
Writes an unsigned integer value to the specified 2-byte location.
PUT-LONG
Writes an integer value to the specified 4-byte location.
PUT-FLOAT
Writes a decimal value to the specified 4-byte location as a single-precision floating-point value.
PUT-DOUBLE
Writes a decimal value to the specified 8-byte location as a double-precision floating-point value.
PUT-STRING
Writes a character string value to the specified location, either null terminated or for a specified number of bytes.
PUT-BYTES
Writes the contents of a RAW or MEMPTR variable to the specified byte location of a RAW or MEMPTR variable.

For more information on these statements, see the Progress Language Reference .

Memory-reading Functions

Progress provides the GET-datatype functions shown in Table 1–2.

Table 1–2: GET-datatype Functions
Function
Description
GET-BYTE
Returns the integer value of the specified 1-byte location.
GET-SHORT
Returns the integer value of the specified 2-byte location.
GET-UNSIGNED-SHORT
Returns the value of the specified 2-byte location, interpreted as an unsigned integer.
GET-LONG
Returns the integer value of the specified 4-byte location.
GET-FLOAT
Returns the decimal value of the specified 4-byte location, interpreted as a single-precision floating-point value.
GET-DOUBLE
Returns the decimal value of the specified 8-byte location, interpreted as a double-precision floating-point value.
GET-STRING
Returns the character string value from the specified location, either null terminated or for a specified number of bytes that can include nulls.
GET-BYTES
Returns, as a MEMPTR or RAW value, the specified number of bytes from the specified byte location of a RAW or MEMPTR variable.

For more information on these functions, see the Progress Language Reference .

Copying Between Basic Progress Data Types and MEMPTR

Table 1–3 lists the basic Progress data types and how you can copy them in and out of a MEMPTR variable.

Table 1–3: Copying Between Basic Progress Data Types
and MEMPTR
Data Type
Copying To/From MEMPTR
DATE
To copy into a MEMPTR:
  • Use INTEGER(date-expression) to obtain an integer value.
  • Use the PUT-LONG statement to copy integer value to MEMPTR.
To copy from a MEMPTR:
  • Use the GET-LONG function to return the integer value.
  • Use the DATE(integer-expression) function to return the date.
DECIMAL1
To copy into a MEMPTR:
  • Use the PUT-DOUBLE or PUT-FLOAT statement.
To copy from a MEMPTR:
  • Use the GET-DOUBLE or GET-FLOAT function.
INTEGER1
To copy into a MEMPTR:
  • Use the PUT-LONG, PUT-SHORT, PUT-UNSIGNED-SHORT, or PUT-BYTE statements.
To copy from a MEMPTR:
  • Use the GET-LONG, GET-SHORT, GET-UNSIGNED-SHORT, or GET-BYTE functions.
LOGICAL1
To copy into a MEMPTR:
  • Use the PUT-LONG, PUT-SHORT, PUT-UNSIGNED-SHORT, or PUT-BYTE statements.
To copy from a MEMPTR:
  • Use the GET-LONG, GET-SHORT, GET-UNSIGNED-SHORT, or GET-BYTE functions.
RAW
To copy into a MEMPTR:
  • Assign the RAW value directly using an assignment statement or use the PUT-RAW statement.
To copy from a MEMPTR:
  • Assign the MEMPTR value directly using an assignment statement or use the GET-RAW function.
  1. The choice of exact statement or function to use depends on the data type used by the shared library routine or the socket application with your application is communicating.

Manipulating Bit Values

You can copy bit values up to the size of a Progress INTEGER from one INTEGER value to another. The statement to copy bit values to an INTEGER variable, PUT-BITS, has the following syntax:

SYNTAX
PUT-BITS( destination , start-position , count ) = integer-expression 

This statement interprets an integer (integer-expression) as the sequence of bits representing the binary value of integer-expression. For example, if the value of integer-expression is 22, the bit sequence is 10110. The statement interprets the INTEGER variable, destination, as a sequence of bits and writes the sequence of bits from integer-expression into destination, starting at the specified bit position (start-position) The bit position in destination is counted from the low-order bit, where the first bit is bit one (1). If the value of integer-expression is too large to store in the specified number of bits, Progress stores the low-order count bits of integer-expression in the specified count bits within destination.

The function to return some number of bits from an INTEGER variable, GET-BITS, has the following syntax:

SYNTAX
GET-BITS( source , start-position , count ) 

This function returns the INTEGER that represents the value of the number of bits specified by count starting at the specified low-order bit position (start-position) within the INTEGER variable specified by source.

Thus, you can store bit values in MEMPTR variables and return bit values from MEMPTR variables by using the PUT-LONG statement and GET-LONG function to store and return the corresponding INTEGER expression that contains the bit pattern.

Copying Between Database Records and MEMPTR

Copying a database record to and from a MEMPTR variable relies on the RAW-TRANSFER statement. This statement allows you to copy a whole database record buffer to a RAW variable or to copy a RAW variable to a database record buffer.

Thus, to store a database record in a MEMPTR variable:

  1. Copy the record buffer to a RAW variable using the RAW-TRANSFER statement.
  2. Assign the RAW variable to the MEMPTR variable or to the specified position in the MEMPTR variable using the PUT-BYTES statement.

To retrieve a database record from a MEMPTR variable:

  1. Assign the MEMPTR variable to a RAW variable or use the GET-BYTES function to copy the specified bytes from the MEMPTR to the RAW variable.
  2. Copy the RAW variable to the record buffer using the RAW-TRANSFER statement.

Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095