/* * Licensed Materials - Property of IBM and/or HCL * * IBM Informix Dynamic Server * (c) Copyright IBM Corporation 1996, 2014 All rights reserved. * (c) Copyright HCL Technologies Ltd. 2017. All Rights Reserved. * *************************************************************************** * * Title: locator.h * * Description: * 'locator.h' defines 'loc_t' the locator struct. * * Note: This file goes to customers. *************************************************************************** */ #ifndef LOCATOR_INCL /* avoid multiple includes */ #define LOCATOR_INCL #include "ifxtypes.h" #include "int8.h" /* Locators are used to store TEXT or BYTE fields (blobs) in ESQL programs. The "loc_t" structure is described below. Fields denoted USER should be set by the user program and will be examined by the DBMS system. Those denoted SYSTEM are set by the system and may be examined by the user program. Those denoted INTERNAL contain data only the system manupilates and examines. If "loc_loctype" is set to LOCMEMORY, then the blob is stored in primary memory. The memory buffer is pointed to by the variant "loc_buffer". The field "loc_bufsize" gives the size of "loc_buffer". If the "loc_bufsize" is set to "-1" and "loc_mflags" is set to "0" and the locator is used for a fetch, memory is obtained using "malloc" and "loc_buffer" and "loc_bufsize" are set. If "loc_loctype" is set to LOCFILE, then the blob is stored in a file. The file descriptor of an open operating system file is specified in "loc_fd". If "loc_loctype" is set to LOCFNAME, the the blob is stored in a file and the name of the file is given. The DBMS will open or created the file at the correct time and in the correct mode. If the "loc_loctype" is set to LOCUSER, "loc_(open/close/read/write)" are called. If the blob is an input to a SQL statement, "loc_open" is called with the parameter "LOC_RONLY". If the blob is an output target for an SQL statement, "loc_open" is called with the parameter "LOC_WONLY". "loc_size" specifies the maximum number of bytes to use when the locator is an input target to an SQL statement. It specifies the number of bytes returned if the locator is an output target. If "loc_loctype" is LOCFILE or LOCUSER, it can be set to -1 to indicate transfer until end-of-file. "loc_indicator" is set by the user to -1 to indicate a NULL blob. It will be set to -1 if a NULL blob is retrieved. If the blob to be retrieved will not fit in the space provided, the indicator contains the size of the blob. "loc_status" is the status return of locator operations. "loc_type" is the "blob" type (SQLTEXT, SQLBYTES, ...). "loc_user_env" is a pointer for the user's private use. It is neither set nor examined by the system. "loc_user_env" as well as the "loc_union" fieds may be used by user supplied routines to store and communicate information. */ typedef struct tag_loc_t { int2 loc_loctype; /* USER: type of locator - see below */ union /* variant on 'loc' */ { struct /* case LOCMEMORY */ { int4 lc_bufsize; /* USER: buffer size */ char *lc_buffer; /* USER: memory buffer to use */ char *lc_currdata_p;/* INTERNAL: current memory buffer */ mint lc_mflags; /* USER/INTERNAL: memory flags */ /* (see below) */ } lc_mem; struct /* cases L0CFNAME & LOCFILE */ { char *lc_fname; /* USER: file name */ mint lc_mode; /* USER: perm. bits used if creating */ mint lc_fd; /* USER: os file descriptior */ int4 lc_position; /* INTERNAL: seek position */ } lc_file; } lc_union; int4 loc_indicator; /* USER SYSTEM: indicator */ int4 loc_type; /* USER SYSTEM: type of blob */ int4 loc_size; /* USER SYSTEM: num bytes in blob or -1 */ mint loc_status; /* SYSTEM: status return of locator ops */ char *loc_user_env; /* USER: for the user's PRIVATE use */ int4 loc_xfercount; /* INTERNAL/SYSTEM: Transfer count */ #if defined(__STDC__) || defined(__cplusplus) mint (*loc_open)(struct tag_loc_t *loc, mint flag, mint bsize); mint (*loc_close)(struct tag_loc_t *loc); mint (*loc_read)(struct tag_loc_t *loc, char *buffer, mint buflen); mint (*loc_write)(struct tag_loc_t *loc, char *buffer, mint buflen); #else mint (*loc_open)(); mint (*loc_close)(); mint (*loc_read)(); mint (*loc_write)(); #endif /* defined(__STDC__) || defined(__cplusplus) */ mint loc_oflags; /* USER/INTERNAL: see flag definitions below */ } loc_t; #define loc_fname lc_union.lc_file.lc_fname #define loc_fd lc_union.lc_file.lc_fd #define loc_position lc_union.lc_file.lc_position #define loc_bufsize lc_union.lc_mem.lc_bufsize #define loc_buffer lc_union.lc_mem.lc_buffer #define loc_currdata_p lc_union.lc_mem.lc_currdata_p #define loc_mflags lc_union.lc_mem.lc_mflags /* Enumeration literals for loc_loctype */ #define LOCMEMORY 1 /* memory storage */ #define LOCFNAME 2 /* File storage with file name */ #define LOCFILE 3 /* File storage with fd */ #define LOCUSER 4 /* User define functions */ /* passed to loc_open and stored in loc_oflags */ #define LOC_RONLY 0x1 /* read only */ #define LOC_WONLY 0x2 /* write only */ /* LOC_APPEND can be set when the locator is created * if the file is to be appended to instead of created */ #define LOC_APPEND 0x4 /* write with append */ #define LOC_TEMPFILE 0x8 /* 4GL tempfile blob */ /* LOC_USEALL can be set to force the maximum size of the blob to always be * used when the blob is an input source. This is the same as setting the * loc_size field to -1. Good for LOCFILE or LOCFNAME blobs only. */ #define LOC_USEALL 0x10 /* ignore loc_size field */ #define LOC_DESCRIPTOR 0x20 /* BLOB is optical descriptor */ /* passed to loc_open and stored in loc_mflags */ #define LOC_ALLOC 0x1 /* free and alloc memory */ /* Flags to indicate if file is on the server or client */ #define LO_CLIENT_FILE 0x20000000 #define LO_SERVER_FILE 0x10000000 #define LO_ALT_NOBUFFER_CUROPEN 0x80000000 /******************************************************************************* * File open flags used for operating system file open via * - ifx_lo_copy_to_lo * - ifx_lo_copy_to_file * - ifx_file_to_file * ******************************************************************************/ #define LO_O_EXCL 0x00000001 /* fail if file exists */ #define LO_O_APPEND 0x00000002 /* append to end of file */ #define LO_O_TRUNC 0x00000004 /* turncate to 0 if file exists */ #define LO_O_RDWR 0x00000008 /* read/write (default) */ #define LO_O_RDONLY 0x00000010 /* read-only (from-flags only) */ #define LO_O_WRONLY 0x00000020 /* write-only (to-flags only) */ #define LO_O_BINARY 0x00000040 /* binary-mode (default) */ #define LO_O_TEXT 0x00000080 /* text-mode (default off)*/ /******************************************************************************* * * Smartblob Definitions * ******************************************************************************/ /****************************************************************************** * Open flags: see ESQL/C documentation for further explanation. * * LO_APPEND - Positions the seek position to end-of-file + 1. Affects write * operations. Reads can still seek anywhere in the LO. Writes always append. * * LO_SEQUENTIAL - If set overrides optimizer decision. Indicates that * reads are sequential in either forward or reverse direction. * * LO_RANDOM - If set overrides optimizer decision. Indicates that I/O is * random and that the system should not read-ahead. * LO_FORWARD - Only used for sequential access. Indicates that the sequential * access will be in a forward direction, i.e. from low offset to higher offset. * LO_REVERSE - Only used for sequential access. Indicates that the sequential * access will be in a reverse direction. * * LO_BUFFER - If set overrides optimizer decision. I/O goes through the * buffer pool. This is the "normal" case. * * LO_NOBUFFER - If set then I/O does not use the buffer pool. Instead the I/O * will use the light I/O private buffers. ******************************************************************************/ #define LO_APPEND 0x1 #define LO_WRONLY 0x2 #define LO_RDONLY 0x4 /* default */ #define LO_RDWR 0x8 #define LO_DIRTY_READ 0x10 #define LO_RANDOM 0x20 /* default is determined by optimizer */ #define LO_SEQUENTIAL 0x40 /* default is determined by optimizer */ #define LO_FORWARD 0x80 /* default */ #define LO_REVERSE 0x100 #define LO_BUFFER 0x200 /* default is determined by optimizer */ #define LO_NOBUFFER 0x400 /* default is determined by optimizer */ #define LO_NODIRTY_READ 0x800 #define LO_LOCKALL 0x1000 /* default */ #define LO_LOCKRANGE 0x2000 #ifndef REMOVE_VECTORIO #define LO_VECTORIO 0x4000 #endif #define LO_SECONDARY_NODE 0x8000 /* secondary node:not primary - sbmach11 */ /* * LO_PSEUDO and LO_SNOOP pseudo-smartblob flags * * Subsytems other than the smartblob subsystem (notably, CDC transaction * capture and CDR, with other users to come) store entries in the * session's open-smartblob table. These entries are not actual smartblobs * (as implemented by tristarp/sblob), instead they simply use the * smartblob interface to access other sources of data, much as eg in Unix * an open file descriptor can refer to, say, a pipe or a file. LO_PSEUDO * and LO_SNOOP flags indicate such "not a real smartblob" entries. */ #define LO_PSEUDO 0x00010000 /* This is a pseudo large object */ #define LO_SNOOP 0x00020000 /* Pseudo-sblob entry for tx capture */ #define LO_TRANSACTION_SURVIVAL 0x40000 /* This call is transaction survival */ #define LO_PRIMARY_NODE 0x80000 #define LO_PUSHDATA 0x00100000 /* See sblob.h for the internal-use open flags list */ /* * Another set of open flags are defined to make the flags more meaningful */ #define LO_OPEN_APPEND LO_APPEND #define LO_OPEN_WRONLY LO_WRONLY #define LO_OPEN_RDONLY LO_RDONLY /* default */ #define LO_OPEN_RDWR LO_RDWR #define LO_OPEN_DIRTY_READ LO_DIRTY_READ #define LO_OPEN_RANDOM LO_RANDOM /* default is determined by optimizer */ #define LO_OPEN_SEQUENTIAL LO_SEQUENTIAL /* default is determined by optimizer */ #define LO_OPEN_FORWARD LO_FORWARD /* default */ #define LO_OPEN_REVERSE LO_REVERSE #define LO_OPEN_BUFFER LO_BUFFER /* default is determined by optimizer */ #define LO_OPEN_NOBUFFER LO_NOBUFFER /* default is determined by optimizer */ #define LO_OPEN_NODIRTY_READ LO_NODIRTY_READ #define LO_OPEN_LOCKALL LO_LOCKALL /* default */ #define LO_OPEN_LOCKRANGE LO_LOCKRANGE /* When setting the MI_LO_NOBUFFER flag for write operations, please * don't set this flag if the object is small. It usually causes a synchronous * flush of the log and a synchronous flush of pages written - this is * very slow. Instead use buffered I/O for small writes. */ #define LO_NOBUFFER_SIZE_THRESHOLD 8080 /*see Informix internal use file /vobs/tristarp/incl/sblob.h for other flags*/ /******************************************************************************* * LO create-time flags: * * Bitmask - Set/Get via ifx_lo_specset_flags() on ifx_lo_create_spec_t. * * New applications should use the flags which begin LO_ATTR_ * The second set of flags are defined for backward compatibility only. ******************************************************************************/ #define LO_ATTR_LOG 0x0001 #define LO_ATTR_NOLOG 0x0002 #define LO_ATTR_DELAY_LOG 0x0004 #define LO_ATTR_KEEP_LASTACCESS_TIME 0x0008 #define LO_ATTR_NOKEEP_LASTACCESS_TIME 0x0010 #define LO_ATTR_HIGH_INTEG 0x0020 #define LO_ATTR_MODERATE_INTEG 0x0040 #define LO_ATTR_TEMP 0x0080 /* these 7 values are defined for backward compatibility only */ #define LO_LOG 0x0001 #define LO_NOLOG 0x0002 #define LO_DELAY_LOG 0x0004 #define LO_KEEP_LASTACCESS_TIME 0x0008 #define LO_NOKEEP_LASTACCESS_TIME 0x0010 #define LO_HIGH_INTEG 0x0020 #define LO_MODERATE_INTEG 0x0040 #define LO_TEMP 0x0080 #define LO_RELOCATED 0x0100 /* see comment below */ #define LO_RELOCATED_PTR 0x0200 /* these flags are defined to make the create flags more meaningful */ #define LO_CREATE_LOG 0x0001 #define LO_CREATE_NOLOG 0x0002 #define LO_CREATE_DELAY_LOG 0x0004 #define LO_CREATE_KEEP_LASTACCESS_TIME 0x0008 #define LO_CREATE_NOKEEP_LASTACCESS_TIME 0x0010 #define LO_CREATE_HIGH_INTEG 0x0020 #define LO_CREATE_MODERATE_INTEG 0x0040 #define LO_CREATE_TEMP 0x0080 #define LO_CREATE_RELOCATED 0x0100 /* this LO was supposed * go into an occuppied row * mach11 */ #define LO_CREATE_RELOCATED_PTR 0x0200 /* this LO points to a * relocated row - mach11 */ #define LO_CREATE_CDR 0x0400 /* This LO is created by ER */ /******************************************************************************* * Symbolic constants for the "lseek" routine ******************************************************************************/ #define LO_SEEK_SET 0 /* Set curr. pos. to "offset" */ #define LO_SEEK_CUR 1 /* Set curr. pos. to current + "offset" */ #define LO_SEEK_END 2 /* Set curr. pos. to EOF + "offset" */ #define LO_SEEK_PSEUDO 40 /* Read from pseudo large object */ /******************************************************************************* * Symbolic constants for lo_lock and lo_unlock routines. ******************************************************************************/ #define LO_SHARED_MODE 1 /* ISSLOCK */ #define LO_EXCLUSIVE_MODE 2 /* ISXLOCK */ #define LO_MAX_END -1 #define LO_CURRENT_END -2 /******************************************************************************* * ifx_lo_create_spec_t: * * This is an opaque structure used for creating smartblobs. The * user may examin and/or set certain fields herein by using * ifx_lo_spec[set|get]_* accessor functions. Prototypes for these acessors * are in incl/sqlhdr.h * ******************************************************************************/ typedef struct ifx_lo_create_spec_s ifx_lo_create_spec_t; /******************************************************************************* * ifx_lo_t: A dummy opaque representation of the smartblob structure * * This can be used for stack or in-line structure declarations. * ******************************************************************************/ #define SB_LOCSIZE 72 /* length of ifx_lo_t */ typedef struct ifx_lo_ts { char dummy[SB_LOCSIZE]; } ifx_lo_t; /******************************************************************************* * ifx_lo_stat: * * This is an opaque structure used in querying attribtes of smartblobs. The * user may examin fields herein by using ifx_lo_stat_* accessor functions. * Prototypes for these acessors are in incl/sqlhdr.h * * The accessors are defined as follows: * ifx_lo_stat_size: contains the size of the LO in bytes. * ifx_lo_stat_uid: reserved for future use: the user id for the * owner of the LO. * ifx_lo_stat_atime: the time of last access. This is only maintained if * the LO_KEEP_LASTACCESS_TIME flag is set for the LO. * Resolution is seconds. * ifx_lo_stat_mtime: the time of last modification. Resolution is * seconds. * ifx_lo_stat_ctime: the time of the last status change (this includes * updates, changes in ownership, and changes to the number of * references). Resolution is seconds. See Appendix B2.11, * Future Embedded- language feature issues, Smartblob API * functions using lofd, for enhancements that extend support * for named and external LOs. * ifx_lo_stat_refcnt: the number of pointers to this LO - when 0 the LO is * typically deleted. See deletion criteria. * ifx_lo_stat_cspec: a pointer to the opaque create spec for this object. * (see ifx_lo_spec[get|set]_ accessors for details.) * ifx_lo_stat_type: the 8 byte code for the LO's type * ******************************************************************************/ typedef struct ifx_lo_stat_s ifx_lo_stat_t; #endif /* LOCATOR_INCL */