4glWorks reference: text blobs manipulation routines

The routines described here return errors via the status global variable. A status of -717 means that at least one of the parameters was invalid (ie blob located in a file, or not initialized, or a wrong string index). -1319 indicates the lack of memory.

asc_addline

file cascc.c
declaration 
function asc_addline(b, s, l)
    define b	text,
	   s	char(32000),
	   l	smallint
returns nothing
purpose adds the text contained in s to b, before line l.
example 
function text_load(t, f)
    define t	text,
	   f	char(80),
	   fd	integer

    call asc_locate(t)
    let fd=file_open(f, "r")
    if (f is not null)
    then
#
#  split lines at word boundaries
#
	call fd_postwordsep(fd, " ")
	while not fd_eof(fd)
	    call asc_line(t, fd_read(fd), "")
	end while
    end if
end function
notes
  • a NLwill be added after the contents of s
  • if l is null, less than 0 or greater than the number of lines in b, the text will be appended at the end of the variable

asc_addstring

file cascc.c
declaration 
function asc_addstring(b, t, i)
    define b	text,
	   t	char(32000),
	   i	integer
returns nothing
purpose adds the text contained in t to b, before character i.
example 
function right_margin(pk, w)
define	pk	integer,
	w	smallint,
	l, p	smallint,
	t	text

    locate t in memory
    select someblob into t from sometable
      where sometable.pk=pk
    asc_initialize(t)
    let l=1
    while (l<=asc_lines(t))
	if (asc_linelength(t, l)>w)
	then
	    let p=asc_linepos(t, l)+w
	    call asc_addstring(t, ascii 10, p)
	end if
	let l=l+1
    end while
    update sometable set someblob=t
      where sometable.pk=pk
    asc_free(t)
end function
notes
  • a NLwill not be added after the contents of t
  • if i is null, less than 0 or greater than the size of b, the text will be appended at the end of the variable

asc_changeline

file cascc.c
declaration 
function asc_changeline(b, t, i)
    define b	text,
	   t	char(32000),
	   i	integer
returns nothing
purpose changes the contents of line l with the text contained in t.
example 
function downshift_text(t)
define	t	text,
	l, m	integer

    let m=asc_lines(t)
    if (status)
    then
	return
    end if
    for l=1 to m
	call asc_changeline(t, downshift(asc_retrieveline(t, l)), l)
    end for
end function
notes If t contains no NL, the line count of b will be unchanged.

asc_changestring

file cascc.c
declaration 
function asc_changestring(b, t, s, e)
    define b	text,
	   t	char(32000),
	   s, e	integer
returns nothing
purpose changes the text contained in b[s, e] with the contents of t.
example 
function upshift_text(t)
define	t	text,
	l, s, e	integer

    let l=asc_length(t)
    if (status)
    then
	return
    end if
    for s=1 to l step 100
	let e=p+99
	if (e>l)
	then
	    let e=l
	end if
	call asc_changestring(t, upshift(asc_retrievestring(t, s, e)), s, e)
    end for
end function
notes none

asc_copy

file cascc.c
declaration 
function asc_copy(b1, b2)
    define b1, b2	text
returns nothing
purpose copies the contents of the text variable b1 into b2
example none
notes
  • asc_copy only copies the contents of text variables from/to blobs located i memory
  • the previous contents of the target variable are lost
  • never free a text variable located with asc_copy with the 4gl FREE statement (which is entirely possible), as this will result in memory leaks

asc_dropline

file cascc.c
declaration 
function asc_dropline(b, l)
    define b	text,
	   l	integer
returns nothing
purpose removes line l from b up to and including the trailing NL
example none
notes none

asc_dropstring

file cascc.c
declaration 
function asc_dropstring(b, s, e)
    define b	text,
	   s, e	integer
returns nothing
purpose removes characters from b staring from position s up to and including e
example none
notes none

asc_free

file cascc.c
declaration 
function asc_free(b)
    define b	text
returns nothing
purpose frees the text variable from memory.
example see asc_addstring
notes never free a text variable located with asc_locate, asc_copy, or asc_initialize with the 4gl FREE statement (which is entirely possible), as this will result in memory leaks

asc_initialize

file cascc.c
declaration 
function asc_initialize(b)
    define b	text
returns nothing
purpose adds line indexing to text variable b
example see asc_addstring
notes never free a text variable located with asc_initialize with the 4gl FREE statement (which is entirely possible), as this will result in memory leaks

asc_length

file cascc.c
declaration 
function asc_length(b)
    define b	text
returns l (integer), the blob size
purpose returns the size in characters of b
example see asc_changestring
notes none

asc_lines

file cascc.c
declaration 
function asc_lines(b)
    define b	text
returns l (integer), the number of lines in the blob
purpose returns the number of lines in b
example see asc_addstring
notes none

asc_linelength

file cascc.c
declaration 
function asc_linelength(b, l)
    define b	text,
	   l	integer
returns c, integer, length of line l
purpose returns the length of line l
example see asc_addstring
notes none

asc_linepos

file cascc.c
declaration 
function asc_linepos(b, l)
    define b	text,
	   l	integer
returns c, integer position of first character of line l
purpose returns the start position of line l within b
example see asc_addstring
notes none

asc_locate

file cascc.c
declaration 
function asc_locate(b)
    define b	text
returns nothing
purpose locates text var in memory and prepares it for blob manipulation.
example see asc_addline
notes
  • the previous contents of the text variable are lost
  • never free a text variable located with asc_locate with the 4gl FREE statement (which is entirely possible), as this will result in memory leaks

asc_retrieveline

file cascc.c
declaration 
function asc_retrieveline(b, l)
    define b	text,
	   l	integer
returns t (char(512)), the line contents.
purpose returns the contents of line l
example 
function text_unload(t, f)
    define t	text,
	   f	char(80),
	   fd	integer

    let fd=file_open(f, "w")
    if (fd is not null)
    then
	for i=1 to asc_lines(t)
	    call fd_writeln(fd, asc_retrieveline(t, i))
	end for
	let i=fd_close(fd)
    end if
end function
notes the string returned does not include the final NL

asc_retrievestring

file cascc.c
declaration 
function asc_retrievestring(b, s, e)
    define b	text,
	   s, e	integer
returns t (char(512)), text variable substring
purpose returns a substring of b starting at position s up to and including e
example see asc_changestring
notes none

Please address questions or comments to marco greco
(last updated Thu, 28 March 2002 16:04:18 GMT)