Home AESAES Form libraryForm library Graphics libraryGraphics library

8.12 Geneva library

This library contains special functions, which only available on Geneva.

• x_help Start the Help display program.
• x_malloc Allocate memory from Geneva.
• x_mfree Free memory allocated with x_malloc.
• x_mshrink Shrink a memory block with x_malloc.
• x_realloc Change the size of memory allocated with x_malloc.
• x_settings Get or set Geneva's internal settings.
• x_sprintf Print data to a string.
• x_sscanf Read formatted data from a string.

See also: About the AES

8.12.1 x_help

Name: »Geneva help« - Inform the Help display program of a request for help text.
 
Opcode: 29061
 
Syntax: int16_t x_help( int8_t *topic, int8_t *helpfile, int16_t sensitive );
 
Description:
 
Parameter Meaning
   
topic Help topic to search for
helpfile GEMDOS file name to search first for the help topic, or NULL to search only GENEVA.HLP.
sensitive 0 = topic is not case-sensitive

This function is used by a program to provide online help for its features.
 
Geneva begins by checking to see if the help display program is already in memory. If it is not, then it is loaded from disk by way of the SHOWHELP environmental variable, as set in GEM.CNF.
 
Once the program is in memory, it is sent a message containing the values passed in the x_help function call. The user is then either shown the help text, or an error message saying that the topic was not found.
 
The topic parameter points to a NUL-terminated string containing the help topic to search for. If sensitive is non-zero, then the case (upper/lower) of the topic must exactly match what is stored in the help file. If, however, sensitive is zero, both the case-sensitive and case-insensitive sections of the help file are searched for the topic.
 
filename points to a NUL-terminated string describing the path and file name of the default help file to search for the topic. If no path information is used, then the PATH environmental variable is searched (by way of shel_find) for the file. If this file is not found, or the topic is not found in the file, the user receives an error message. If filename is NULL (0L), then the topic is only searched for in GENEVA.HLP.
 
Return value: An error code (0) is returned if either the help program could not be loaded, or there was insufficient free memory to send the message.
 
Availability: The function is only available under Geneva.
 
Group: Geneva library
 
See also: Binding
 

8.12.1.1 Bindings for x_help

C: int16_t x_help( int8_t *topic, int8_t *helpfile, int16_t sensitive );
 
Binding:
  
int16_t x_help( int8_t *topic, int8_t *helpfile, int16_t
sensitive )
{
   int_in[0] = sensitive
   addr_in[0] = topic;
   addr_in[1] = helpfile;

   crys_if(29061);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29061 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] sensitive
addr_in addr_in[0] topic
addr_in+4 addr_in[1] helpfile
int_out int_out[0] Return value

8.12.2 x_malloc

Name: »memory allocation« - Allocate memory from Geneva.
 
Opcode: 29062
 
Syntax: void x_malloc( void **addr, int32_t size );
 
Description:
 
Parameter Meaning
   
size Number of bytes to be reserved
addr Pointer to a pointer which receives the address of an allocated block, or 0L

This function allocates memory, much in the same way Malloc or malloc does. The only major difference is that it comes without the extra overhead of malloc. Since Geneva takes this memory from the same pool as the rest of its memory, it is also not as likely to cause memory fragmentation if the application allocates lots of small blocks using this call as it is when doing so with Malloc.
 
If no memory could be allocated, the addr is set to NULL (0L).
 
Unlike the GEMDOS Malloc function, this function does not accept the "size" -1L.
 
Return value: The function have no return value.
 
Availability: The function is only available under Geneva since Release 004.
 
Group: Geneva library
 
See also: Binding
 

8.12.2.1 Bindings for x_malloc

C: void x_malloc( void **addr, int32_t size );
 
Binding:
  
void x_malloc( void **addr, int32_t size )
{
   (int32_t)int_in[0] = size;

   addr_in[0] = addr;

   crys_if(29062);

   return;
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29062 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] MSW of the size
int_in+2 int_in[1] LSW of the size (lower 16 bits)
addr_in addr_in[0] addr

8.12.3 x_mfree

Name: »memory free« - Free memory allocated with x_malloc.
 
Opcode: 29063
 
Syntax: int16_t x_mfree( void *addr );
 
Description:
 
Parameter Meaning
   
addr Pointer to a memory block previously allocated with x_malloc.
Return value: 0 = Success
other = Failure
 
Availability: The function is only available under Geneva since Release 004.
 
Group: Geneva library
 
See also: Binding
 

8.12.3.1 Bindings for x_mfree

C: int16_t x_mfree( void *addr );
 
Binding:
  
int16_t x_mfree( void *addr )
{
   addr_in[0] = addr;

   crys_if(29063);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29063 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] addr
int_out int_out[0] Return value

8.12.4 x_mshrink

Name: »memory shrink« - Shrink a memory block allocated with x_malloc.
 
Opcode: 29064
 
Syntax: int16_t x_mshrink( void *addr, int32_t newsize );
 
Description:
 
Parameter Meaning
   
addr Pointer to a memory block previously allocated with x_malloc.
newsize New size of the memory block.

This function shrinks (decreases the size of) a block of memory previously allocated with the x_malloc function. The newsize must be less than the original size, or Failure will be returned.
 
Return value: 0 = Success
other = Failure
 
Availability: The function is only available under Geneva since Release 004.
 
Group: Geneva library
 
See also: Binding
 

8.12.4.1 Bindings for x_mshrink

C: int16_t x_mshrink( void *addr, int32_t newsize );
 
Binding:
  
int16_t x_mshrink( void *addr, int32_t newsize )
{
   int_in[0-1] = newsize;    /* int_in[0] MSW of the size */
                             /* int_in[1] LSW of the size (lower 16 bits) */
   addr_in[0] = addr;

   crys_if(29064);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29064 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] newsize; MSW of the size
int_in+2 int_in[1] newsize; LSW of the size (lower 16 bits)
addr_in addr_in[0] addr
int_out int_out[0] Return value

8.12.5 x_realloc

Name: »memory realloc« - Change the size of memory allocated with x_malloc.
 
Opcode: 29065
 
Syntax: int16_t x_realloc( void **addr, int32_t newsize );
 
Description:
 
Parameter Meaning
   
addr Pointer to a memory block previously allocated with x_malloc.
newsize New size of the memory block.

This function changes the size of a block of memory previously allocated with the x_malloc function. If newsize is greater than the block's original size, it may be necessary for Geneva to move the block to a new location. If there is insufficient free memory to increase the size of the block, the "old" block continues to reside where it was and an error code is returned.
 
Return value: 0 = Success
other = Failure
 
Availability: The function is only available under Geneva since Release 004.
 
Group: Geneva library
 
See also: Binding
 

8.12.5.1 Bindings for x_realloc

C: int16_t x_realloc( void **addr, int32_t newsize );
 
Binding:
  
int16_t x_realloc( void **addr, int32_t newsize )
{
   int_in[0-1] = newsize;    /* int_in[0] MSW of the size */
                             /* int_in[1] LSW of the size (lower 16 bits) */
   addr_in[0] = addr;

   crys_if(29065);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29065 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] newsize; MSW of the size
int_in+2 int_in[1] newsize; LSW of the size (lower 16 bits)
addr_in addr_in[0] addr
int_out int_out[0] Return value

8.12.6 x_settings

Name: »Geneva settings« - Get or set Geneva's internal settings.
 
Opcode: 29056
 
Syntax: int16_t x_settings ( int16_t getset, int16_t length, SETTINGS *user );
 
Description:
 
Parameter Meaning
   
getset 0 = Get, 1 = Set, -1 = Reset
length length of bytes to get or set
user Points to SETTINGS to get or set, or NULL

0: Get
Read length bytes (or the maximum length of the SETTINGS structure.) Setting length to a negative number will read the whole structure, though this is not recommended since future versions may expand the SETTINGS structure.
 
Example:
  
SETTINGS set;
x_settings ( 0, sizeof(set), &set );

1: Set
Set length bytes (or the maximum length of the SETTINGS structure.) Setting length to a negative number will set the whole structure, though this is not recommended since future versions may expand the SETTINGS structure. The contents of user are not modified.
 
Example: Temporarily disable pulldowns:
  
SETTINGS set;
x_settings ( 0, sizeof(set), &set ); /* get current        */
set.pulldown = 0;
x_settings ( 1, sizeof(set), &set ); /* turn off           */
...                                  /* do some stuff here */
set.pulldown = 1;
x_settings ( 1, sizeof(set), &set ); /* turn back on       */

-1: Reset
Reset length bytes of the settings to their default values. If length is less than zero, all of the settings will be reset. The user parameter can be NULL, since it is not used.
 
Return value: The function always returns 1.
 
Availability: The function is only available under Geneva.
 
Group: Geneva library
 
See also: Binding
 

8.12.6.1 Bindings for x_settings

C: int16_t x_settings ( int16_t getset, int16_t length, SETTINGS *user );
 
Binding:
  
int16_t x_settings ( int16_t getset, int16_t length, SETTINGS
*user )
{
   int_in[0] = getset;
   int_in[1] = length;
   addr_in[0] = user;

   crys_if(29056);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29056 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] getset
int_in+2 int_in[1] length
addr_in addr_in[0] user
int_out int_out[0] Return value

8.12.7 x_sprintf

Name: »Geneva sprinft« - Print data to a string, with extended formats.
 
Opcode: 29059
 
Syntax: void x_sprintf( int8_t *buf, int8_t *fmt, ... );
 
Description:
 
Parameter Meaning
   
buf Buffer to receive output string
fmt Null-terminated format string
... Pointer to first argument on user stack

This function acts almost identically to the sprintf function found in C programming libraries. It understands the following format specifiers:
 

%c Character
%s String
%x Unsigned int in hexadecimal
%X Unsigned long in hexadecimal
%d Signed int in decimal
%D Signed long in decimal
%o Signed int in octal
%b Boolean: 'F' for 0, or 'T' for non-zero
%k When passed a pointer to a KEYCODE structure, output
all three elements using the format "%02x %02x %02x"
%v Take the int argument and output the MSB and LSB in the
format "%x.%02x". Used for generating version numbers.
%S Surround the string with curly braces, so that a string
containing spaces can be read back in correctly with
the x_sscanf function
%h Same as %x

These prefixes can be used before the string and number formats:
 

- Left-justified, instead of right-justified
0 Pad with 0's insteausof spaces
0-9 Any number of digits (following a possible first '0'
for padding) specify the field length, in decimal 
Example:                                   Result:
x_sprintf( str, "%04x", 0xFE );            00FE
x_sprintf( str, "%-06s", "Hi!" );          Hi!000
x_sprintf( str, "%6s", "Hi!" );            Hi!
x_sprintf( str, "%b %v", 2, 0x502 );       T 5.02
x_sprintf( str, "%S %s", "a b", "c d" );   {a b} c d
KEYCODE key = { 1, 0, 'X' };
x_sprintf( str, "key=%k", &key );          keyd 1 00 58

This sort of thing doesn't really belong in a GUI, but it made sense to include it, since it is used by Geneva internally, anyway.
 
Return value: The function have no return value.
 
Availability: The function is only available under Geneva.
 
Group: Geneva library
 
See also: Binding
 

8.12.7.1 Bindings for x_sprintf

C: void x_sprintf( int8_t *buf, int8_t *fmt, ... );
 
Binding:
  
void x_sprintf( int8_t *buf, int8_t *fmt, ... )
{
   addr_in[0] = buf;
   addr_in[1] = fmt;
   addr_in[2] = &...;

   crys_if(29059);

   return;
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29059 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] buf
addr_in+4 addr_in[1] fmt
addr_in+8 addr_in[2] ...

8.12.8 x_sscanf

Name: »Geneva sscanf« - Read formatted data from a string, with extended formats.
 
Opcode: 29060
 
Syntax: void x_sscanf( int8_t *buf, int8_t *fmt, ... );
 
Description:
 
Parameter Meaning
   
buf Buffer containing data
fmt Null-terminated format string
... Pointer to first argument on user stack

This function acts almost identically to the sscanf function found in C programming libraries. It understands the following format specifiers:
 

%c Character
%s String
%x Unsigned int in hexadecimal
%X Unsigned long in hexadecimal
%d Signed int in decimal
%D Signed long in decimal
%o Signed int in octal
%b Boolean: 'F' for 0, or 'T' for non-zero
%k When passed a pointer to a KEYCODE structure, output
all three elements using the format "%02x %02x %02x"
%v Take the int argument and output the MSB and LSB in the
format "%x.%02x". Used for generating version numbers.
%S Surround the string with curly braces, so that a string
containing spaces can be read back in correctly with
the x_sscanf function
%h Unsigned char in hexadecimal 
Example:                                   Result:
int i;
char str[10], str2[10], bool;
KEYCODE key;
x_sscanf( "FE", "%x", &i );                i = 0xFE
x_sscanf( "Hi!", "%s", str );              str = "Hi!"
x_sscanf( "T 5.02", "%b %v", &bool, &i );  bool = 1, i = 0x502
x_sscanf( "{a b} c", "%S %s", str, str2 ); str = "a b", str2 = "c"
x_sprintf( "01 00 58", "%k", &key );       key = { 1, 0, 58 };

This sort of thing doesn't really belong in a GUI, but it made sense to include it, since it is used by Geneva internally, anyway.
 
Return value: The function have no return value.
 
Availability: The function is only available under Geneva.
 
Group: Geneva library
 
See also: Binding
 

8.12.8.1 Bindings for x_sscanf

C: void x_sscanf( int8_t *buf, int8_t *fmt, ... );
 
Binding:
  
void x_sscanf( int8_t *buf, int8_t *fmt, ... )
{
   addr_in[0] = buf;
   addr_in[1] = fmt;
   addr_in[2] = &...;

   crys_if(29060);

   return;
}
GEM-Arrays:
 

Address Element Contents
control control[0] 29060 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] buf
addr_in+4 addr_in[1] fmt
addr_in+8 addr_in[2] ...
Home AESAES Form libraryForm library Graphics libraryGraphics library