Parent | Child | Previous | Next
 
Xbasic

Xbasic Functions and Methods V9

IN THIS PAGE

Description

A list of the functions and methods created for Alpha Five version 9.

Summary of Functions and Methods in Version 9

  • *AT_Multi()

    Searches for the position where any one of a CR-LF delimited list of search strings occurs in another string. Case-sensitive.

  • *ATC_Multi()

    Same as *AT_Multi() but case-insensitive.

  • *Locale()

    Represents text in a specified locale (e.g. Polish), so that it can be sorted correctly in that locale.

  • *gzip_blob()

    Compresses a blob variable using Gzip encoding.

  • *gzip_text()

    Un-compresses a previously Gzip encoded character variable.

  • *guid_create()

    Returns a GUID value (of type K)

  • a5_Active_Link_CreateReadOnly()

    Create an ad-hoc, read-only active-link table definition.

  • a5_ADO_ResolveConnectionString()

    Takes a named ADO connection string and resolves it, returning the actual connection string. The named connection string is of the form: ::Name::connectionstringname.

  • A5_ConnStringOperation()

    Create, edit and delete named AlphaDAO or ADO connection strings.

  • a5_ConnStrings_List()

    Gets a list of the saved AlphaDAO or ADO named connections.

  • a5_GetNamedConnectionString()

    Get the explicit connection string for a given name.

  • a5_Convert_ActiveLink_to_Named_Connections()

    Converts connection strings in all active-link tables from explicit to named connections. If flag is .t., then converts named connection strings to explicit connection strings.

  • a5_GetArgumentValue()

    Gets the current value of an argument. Used in Layouts in a calculated field to print the value of an argument.

  • A5_show_URL()

    Opens a live browser window showing the contents of a URL.

  • a5_HTML_Pretty()

    Takes a string of HTML text and reformats it to show proper indentation of all of the tags.

  • a5_NamedConnectionCreate()

    Creates a named ADO or AlphaDAO connection string.

  • a5_ServerSide_FilterOrder_Get()

    Returns information about the current server-side filter and order that has been applied to an active-link table.

  • .IsDirty()

    Returns .t. if any field on the browse has been changed.

  • email_send_low()

    Send an email message without having to rely on a pre-configured email Profile.

  • Filter_String_Smatch_Change()

    Combines Filter_string_smatch() and stritran_multi() into a single, more efficient function call. Used to change lines of text that match a pattern.

  • .IsDirty()

    Returns .t. if any field on the form has been changed.

  • http_date()

    Takes an input value (of type character, date, or time) and returns an HTTP/1.1 formatted date. If no input value is supplied, uses the current time. Example: "Wed, 04 Jun 2008 19:43:09 GMT"

  • .Refresh()

    Refreshes all of the controls on a form or browse layout. Useful if you have changed the value in a field by getting a pointer to the table and then setting the field value using Xbasic. Similar to the .Resynch() method, but can be executed when the table is in change or enter mode.

  • .ServerSideQueryRun() 

    Applies a server-side filter and order to the primary table of a form or browse (if that table is an active-link table). Allows filters to be applied incrementally. I.e. each filter can be applied to search in the sub-set of previously found records. If this method is called repeatedly with the additive option set to .t., a stack of previously applied filters is maintained.

  • .ServerSideQueryRetract()

    Removes the most recently applied server-side filter.

  • .ServerSideQuery_Show_All()

    Removes all incremental server-side filters from the primary table of a form or browse (if that table is an active-link table).

  • .ServerSideRefreshAll()

    Refreshes all rows in the active-link table. Re-executes the query used to populate the active-link table, so any records added to the server side table after the active-link table was opened will become visible. Contrast with the F5 key (Refresh command) which refreshes the current row with focus.

  • Merge_variable_frames()

    Merges the variables from two different variable frames (i.e. two different dot variable) into a single variable frame.

  • Ping()

    Ping a URL to see if it is responding.

  • Table.External_Suggest()

    Returns a list of values from a field in a table that start with a specified string. See also .Suggest()

  • SQL_Lookup()

    Does a lookup into a table in a remote database using AlphaDAO. Returns a field value or expression from the remote table.

  • SQL_Records_Get()

    Returns a CRLF delimited string with data from a table or query in a remote database using AlphaDAO.

  • Sql_get_Values()

    Similar to SQL_Records_Get(), but allows you to set a LIMIT on number of returned rows.

  • SSL_test_cert()

    Used to test a certificate and its matching key file to make sure they are valid for use in the Application Server.

  • .ServerSideQueryRun()

    Filters the records in an active-link table. The query is performed on the server. Allows filters to be applied incrementally. I.e. each filter can be applied to search in the sub-set of previously found records. If this method is called repeatedly with the additive option set to .t., a stack of previously applied filters is maintained.

  • .ServerSideQueryRetract()

    Removes the most recently applied server-side filter.

  • .ServerSideQueryRetractAll()

    Removes all incremental server-side filters.

  • .ServerSide_Records_Get()

    Returns the number of records in an active-link table. Faster than .Records_Get() because it does not cause the local record cache to become fully populated.

  • .Suggest()

    Returns a list of values from a field in a table that start with a specified string. See also Table.External_Suggest()

  • .To_sql_expression()

    For an active link table, takes an expression that references field names in the active link table and converts it to an expression in SQL syntax that references the corresponding fields in the remote table. If the expression cannot be converted, returns a null string.

  • .To_sql_filter()

    For an active link table, takes a filter expression that references field names in the active link table and converts it to an expression in SQL syntax that references the corresponding fields in the remote table. If the expression cannot be converted, returns a null string. Also returns the portion of the filter expression that could not be converted to SQL syntax.

  • .To_sql_order()

    For an active link table, takes an order expression that references field names in the active link table and converts it to an order expression in SQL syntax that references the corresponding fields in the remote table. If the expression cannot be converted, returns a null string.

  • *XML_DOCUMENT()

    Parses text into an xml document object (useful for immediate access to xml document/node functionality without having to instantiate the XMLSchemaManager.

  • *XML_PEEK_ATTRIBUTE()

    Extracts an attribute value from a snippet of XML text.

Detailed Description of V9 Functions

  • *AT_Multi() and *ATC_Multi() Functions

    Searches for the position where any one of a CRLF delimited list of search strings occurs in another string. *At_multi() is case-sensitive. Syntax: N position = *AT_MULTI(C search_strings,C string[,N occurrence]) Example: The following example will return the position in the search string where the first occurrence of either 'blue' or 'yellow' is found.

    string = "red,green,blue,red,yellow,blue,red,orange"
search = comma_to_crlf("yellow,blue")
?*atc_multi(search,string,1)
= 11


search = comma_to_crlf("blue,yellow")
?*atc_multi(search,string,1)
= 11
?substr(string,11)
= "blue,red,yellow,blue,red,orange"

  • *Locale() Function

    Represents text in the specified locale so that it can be sorted correctly. Syntax C text *locale(C text, C locale)

  • *Gzip_blob() Function

    Compresses a blob variable. Result is a blob. The amount of compression will depend on the size of the input blob. Compressing a small blob might result in blob that is actually larger than the input blob. Syntax: B blob = *gzip_blob(B blob)

  • *Gzip_text() Function

    Compresses a text variable. Result is a blob. The amount of compression will depend on the size of the input string. Compressing a small string might result in blob that is actually larger than the input string. Syntax: B blob = *gzip_text(C string) Example Interactive Window usage: 

    dim bigtext as c
bigtext = replicate("This is a test of the gzip library",20)
b = *GZIP_TEXT(bigtext)
? b.size()
= 48

? len(bigtext)
= 680

  • *Gunzip_Blob () Function

    Un-compresses a blob variable that was previously compressed using *gzip_blob() Syntax: B blob = *Gunzip_Blob (B data)

  • *Gunzip_Text() Function

    Un-compresses a blob variable that was previously compressed using *gzip_text() Syntax: C string = *Gunzip_Text(B data) Example Interactive Window usage: 

    dim bigtext as c
bigtext = replicate("This is a test of the gzip library",20)
b = *GZIP_TEXT(bigtext)
? b.size()
= 48

? len(bigtext)
= 680

bigtext2 = *gunzip_text(b)
? len(bigtext2)
= 680

? bigtext = bigtext2
= .T.

  • a5_Active_Link_CreateReadOnly() Function

    Used to create an ad-hoc, read-only active-link table definition. Syntax: L flag = a5_Active_Link_CreateReadOnly(C table_filename ,C connectionString ,C selectStatement [,L flagAddTableToDatabse ])

    • flag

      .T. if active-link definition was created.

      table_filename

      Filename of the .dbf table (i.e. the active-link table definition)

      connectionString

      The connection string to the remote database.

      flagAddTableToDatabase

      Specify if the active-link table should be added to the current database. If you are creating a temporary active-link definition, it is much faster if you do NOT add it to the current database.

    • Example: The following code creates an an active-link table using a saved connection string to the sample Northwind database. The active-link table has just two columns, customerId and ContactName. A default browse is then opened to show the data in the active-link table. 

      a5_Active_Link_CreateReadOnly("c:\mydata\temptable.dbf","::name::northwind","select customerid, contactname from customers",.f.)
a5_open_default_browse("c:\mydata\temptable.dbf")

  • a5_ADO_ResolveConnectionString() Function

    Used to resolve a named ADO connection string to the actual connection string. Syntax: C ConnectionString = a5_ADO_ResolveConnectionString(C NamedConnectionString) If you pass in an already resolved connection string to this function, it just returns the input connection string. This means that it is safe to wrap the connection string in this function, regardless of whether it is a named connection string, or an explicit connection string. Examples: 

    ?a5_ADO_ResolveConnectionString("::name::MySalesData")
= "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\SalesData.mdb;Persist Security Info=False"
?a5_ADO_ResolveConnectionString("Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\SalesData.mdb;Persist Security Info=False")
= "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\SalesData.mdb;Persist Security Info=False"

  • A5_ConnStringOperation() Function

    Create, edit and delete named AlphaDAO or ADO connection strings. Syntax: a5_ConnStringOperation(C conn_mode ,C name ,C operation [,C library [,C data ]]) Where:

    • conn_mode

      Either 'AlphaDAO' or 'ADO' depending on the type of named connection string you want to edit/create/delete.

      name

      Name of the named connection string.

      operation

      'Save' or 'Delete'. If you use 'Save' and a connection string with the specified name exists, the existing named connection is replaced. If there is no existing named connection, and new named connection is created.

      library

      Leave blank if the connection strings are to be stored in the current Database library. Otherwise you can specify the filename of another Database library (e.g. the .alb file)

      data

      The connection string.

    • Example:

      'Create a connection string called 'MyNewConnectionStrng'
dim cs as c 
cs = "{A5API=MySQL,Server='svr2',Port='3306',UserName='sam',Password=' ',Database='db1'}"
a5_connstringoperation("AlphaDao","MyNewConnectionString","save","",cs)

  • a5_ConnStrings_List() Function

    Gets a list of the saved AlphaDAO or ADO named connections. Syntax: C names = a5_ConnStrings_List as c ([C Mode [, C dictionary]]) Where:

    • dictionary

      Dictionary (i.e. .alb file) where the connections are stored. Enter a blank value to get named connections in the current database.

      mode

      'ADO', or 'AlphaDAO'

    • ?a5_ConnStrings_List("AlphaDAO")
Adventureworks
Alphasports
Northwind

  • a5_GetNamedConnectionString() Function

    Get the explicit connection string for a given name. Syntax: C Explicit_Connection_String = a5_GetNamedConnectionString(C Named_Connection_String [, C type]) Where:

    • Named_connection_string

      Named connection string to resolve

      type

      'ADO', or 'AlphaDAO'

    • Example:

      ?a5_GetNamedConnectionString("Northwind")
= "{A5API=Access,FileName='C:\northwind\northwind.Mdb',UserName='Admin'}"

  • A5_GetArgumentValue() Function

    Gets the value of an argument. Syntax: C Result = a5_getArgumentValue(C argumentName) This function is used in a calculated field in a Layout when you want to print the current value of an argument.

  • A5_show_URL() Function

    Opens a live browser window showing the contents of a URL. Syntax: A5_show_URL( C target_URL [, C title [, C widthInInches [, C heightInInches [, L resizeable]]]]) Example: 

    a5_show_url("http://www.google.com","Search")

  • a5_ServerSide_FilterOrder_Get()

    Returns information about the current server-side filter and order that has been applied to an active-link table. Syntax P Properties = a5_ServerSide_FilterOrder_Get(P TblPointer) Example 

    t = table.open("customers")
p = a5_ServerSide_FilterOrder_Get(tbl)

  • The function returns a dot variable with the following properties:

    IsActiveLinkTable

    Returns .t. or .f. depending on whether the table is an active-link table or not.

    BaseFilter

    Returns the WHERE clause for the SQL SELECT statement used in the active-link table definition.

    IncrementalFilter

    Returns any incremental server-side filters that were applied after the table was opened.

    CompleteFilter

    The complete WHERE clause of the current SQL SELECT statement for the active-link table (base filter and incremental filter ).

    CurrentOrder

    The ORDER BY clause of the current SQL SELECT statement for the active-link table.

    DBFColumnOrder

    If the current server-side sort order maps to a single field in the active-link table, then this contains the name of the field in the active-link table

    DBFColumnDirection

    Either 'Ascending' or 'Descending'

    HasError

    Returns .t. if the SQL statement for the active-link table could not be parsed.

    ErrorText

    If HasError is .t., the error text.

  • Email_send_low() Function

    Send an e-mail message without using a pre-defined Profile. Syntax: L flag = email_send_low as l (C from_emailAddress, C from_name, C message_html, C message_plaintext , C message_subject ,C to_emailAddresses ,C user_name , C password ,C smtp_address as c [,N port = 25 ]) Profiles are defined by selecting the View, Settings, E-mail command. However, there may be situations in which a profile has not been defined where this function is useful.

    To send an email using a Profile, use the email_send() function.

  • Where:

    • from_emailAddress

      The sender's e-mail address

      from_name

      The sender's name

      message_html

      The message in HTML format

      message_plaintext

      The message in plaintext format

      message_subject

      The message subject

      to_emailAddress

      The recipient's e-mail address. This can be a comma delimited list of addresses.

      user_name

      The user name of the sender's e-mail account.

      password

      The password of the sender's e-mail account.

      smtp_address

      The address of the SMTP server.

      port

      The port. Default value is 25

      flag

      Returns .t. if message was sent.

  • Filter_String_Smatch_Change() Functio

    Combines Filter_string_smatch() and stritran_multi() into a single, more efficient function call. Used to change lines of text that match a pattern. Syntax: C Result = FILTER_STRING_SMATCH_CHANGE(C string , C pattern, C changes [,C delimiter]])"

  • Where:

    • string

      The string in which to search.

      pattern

      The pattern that defines which words (lines in the case where the delimiter is CR-LF) to replace.

      changes

      A delimited list of words (lines in the case where the delimiter is CR-LF) to replace the words (or lines) selected by the pattern.

      delimiter

      The delimiter between words in the string.

    • Example:

      input = <<%str%
A|one
C|one
A|two
B|one
A|three
B|two
B|three
C|two
%str%

replace = <<%str%
A|une
A|deux
A|trois
%str%


dim changed as c
changed = FILTER_STRING_SMATCH_CHANGE(input,"A|*",replace)

?changed 
A|une
C|one
A|deux
B|one
A|trois
B|two
B|three
C|two

'In this example, the pattern selected these lines:
A|one
A|two
A|three

'The replacement string replaced each line in the list of selected lines with 
'the corresponding line in the replacement string.

  • .ServerSideQueryRun() Method

    Applies an incremental filter to an active-link table. The query is executed on the server. Contrast with .QueryRun(), which applies an incremental filter by running a local query. Syntax: N RecordsFound = .ServerSideQueryRun(C filter ,C order [,L additive ])

    • Where:

    • RecordsFound

      Returns the number of records found by the query. If the layout is not based on an active-link table, returns -1. The layout is based on an active-link table that does not allow incremental server-side querying, returns -2. For example, an active-link table that was based on a stored procedure would not allow incremental server-side querying.

      filter

      The filter expression. The filter expression must use portable SQL syntax. The filter is in addition to any filter that was defined when the active-link table was defined. For example if the SELECT statement for the active-link table was SELECT * FROM customers WHERE state = 'MA', then the active-link table will always have a base filter of state = 'MA'. I.e. any filter that is specified is in addition to the base filter.

      order

      The order expression. The order expression must use portable SQL syntax.

      additive

      Specifies if the filter should be in addition to any previous filters applied using the .ServerSideQueryRun() method.

    • Examples: The following Interactive Window session shows how the .ServerSideQueryRun() method can be used: 

      'assume that the 'customers' browse is based on an active-link table
p = Browse.Open("customers")

'sort data by city, without changing the filter
? p.ServerSideQueryRun("","City",.t.) 
= 1000

'sort by lastname for city = 'London'
?p.ServerSideQueryRun("city='London'","lastname",.f.)
= 20

'search for title = 'manager' (additive)
'because additive is specified, the full filter is city = 'London' and title = 'manager'
'since the previous query was city = 'London'
?p.ServerSideQueryRun("title = 'manager'","",.t.)
= 5

'search for title = 'manager' (not additive)
'since the query is not additive, the full filter is title = 'manager' (i.e. previous queries are ignored)
?p.ServerSideQueryRun("title = 'manager'","",.f.)
= 345

  • .ServerSideQueryRetract() Method

    Removes the previously applied server-side incremental filter to the primary table of a browse or form layout (assuming that the primary table is an active-link table). The server-side query is applied using the .ServerSideQueryRun() method. This method has an additive parameter. If the .ServerSideQueryRun() method is called with additive set to .t. then the queries are added to a stack. The .ServerSideQueryRetract() method removes the last query from the stack. To remove all queries from the stack, see the .ServerSideQuery_Show_All() method. Syntax: L Result = .ServerSideQueryRetract()

  • .ServerSideQuery_Show_All() Method

    Removes all of the previously applied server-side incremental filters to the primary table of a browse or form layout (assuming that the primary table is an active-link table). To retract just the last applied incremental server-side filter, use the .ServerSideQueryRetract() method. Syntax: L Result = .ServerSideQuery_Show_All()

  • Merge_Variable_Frames() Function

    Merges the variables in two different variable frames (i.e. 'dot' variables) into a single variable frame. Syntax V merge_variable_frame(P dominantFrame, P otherFrame)

    • Where:

    • dominantFrame

      A dot variable containing one or more sub-variables. If the otherFrame contains a variable of the same name, the variable value from the dominantFrame is used.

      otherFrame

      A dot variable containing one or more sub-variables.

    • Example

      'Assume that you have two dot variables (v1, and v2)  defined as follows:
dim v1 as p 
v1.name = "John"
dim v1.cities[1] as c 
v1.age = 23
dim v1.arr[3] as p 
v1.arr[1].item1 = "Row1 - item1"
v1.arr[1].item2 = "Row1 - item2"


dim v2 as p 
v2.name = "Harry"
v2.occupation = "Lawyer"
dim v2.cities[3] as c 
v2.cities[1] = "Boston"
v2.cities[2] = "New York"
v2.cities[3] = "Chicago"

'Now merge these dot variables, with V2 as the 'dominant' frame
merge_variable_frames(v2,v1)

'Now use the *variable_to_script() function to see what the resulting variable frame looks like:
?variable_to_script(v2)
DIM age as N = 23
DIM arr[3] as P
DIM arr[1].item1 as C = "Row1 - item1"
DIM arr[1].item2 as C = "Row1 - item2"
DIM name as C = "Harry"
DIM occupation as C = "Lawyer"
DIM cities[3] as C
cities[1] = "Boston"
cities[2] = "New York"
cities[3] = "Chicago"

  • Ping() Function

    Ping a URL. Returns .T. if a response is received. Can optionally return additional information Syntax L Result = Ping(C URL [, P status])

    • Examples:

      'basic ping
?ping("www.google.com")
= .T.

?ping("no.such.host")
= .F.

'ping with extended status info
dim pResult as p
?ping("www.google.com",pResult)
= .T.

?pResult
= Bytes = 32
StatusCode = 0
StatusText = "Success"
Text = "www.google.com (64.233.169.99) is responding"
Time = 20
TTL = 241

  • Table.External_Suggest()

    Returns a list of suggestions from a field or expression in a table. Syntax C Suggestions = Table.External_Suggest(C tablename, C expr,C value [,N limit [, C more_text [, C filter ]]]) Similar to .Suggest(), but does not require a pointer to an open table. This method will automatically open the table in order to get the suggestions. See .Suggest() for example.

  • SQL_Lookup() Function

    Gets a value from a table in a remote database using AlphaDAO. Syntax: A value = sql_lookup(C connection ,C table ,C filter, C result_Expression [,SQL::arguments arguments ] )

    • Where:

    • value

      Value returned by the function. Can be of any type, depending on the value that result_expression evaluates to.

      connection

      An explicit AlphaDAO connection string, or a named connection string. (e.g. ::name::myconnectionstring), or a pointer to an open connection.

      table

      The name of the table in the remote database in which to perform the lookup.

      filter

      A filter expression to determine which record in the remote table to find. The filter expression must use SQL syntax and must use portable AlphaDAO functions. For example, strings must be single quoted, the AND, OR and NOT operators are not surrounded by periods. The filter expression can use arguments. For example, customerid = :whatcustomerid

      result_Expression

      A expression to determine what value gets returned. The expression can be as simple as a single column name in the remote table, or it can be a complex expression. The expression must be written using portable AlphaDAO syntax.

      arguments

      If the filter expression includes arguments, you must supply argument values using a SQL::arguments object.

    • Examples:

      connection = "{A5API=Access,FileName='C:\northwind2\northwind2003.mdb',UserName='Admin'}"
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "customerid = 'bolid'"
?sql_lookup(connection,table,filter,result_expression)
= "Madrid - Mart n Sommer"

'This example uses a named connection string and it uses arguments in the filter
connection = "::Name::Northwind"
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "customerid = :whatcustomerid"
dim args as sql::arguments
args.set("whatcustomerid","Bolid")
?sql_lookup(connection,table,filter,result_expression,args)
= "Madrid - Mart n Sommer"

'In this example we pass in an open connection. 
'Since the function will not have to open and then close the connection, it is significantly faster
dim cn as sql::connection
cn.open("::Name::Northwind")
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "customerid = 'bolid'"
?sql_lookup(cn,table,filter,result_expression)
= "Madrid - Mart n Sommer"

  • SQL_Records_Get() Function

    Returns a CRLF delimited string with data from a table or query in a remote database using AlphaDAO. Syntax: C Result = SQL_Records_Get (C connection,C table_or_sql_statement,C filter,C result_Expression [,SQL::Arguments args] )

    • Where:

    • result

      A CRLF delimited string of data from the remote table or query. CRLFs in the data are encoded as '\cr\lf'.

      connection

      An explicit AlphaDAO connection string, or a named connection string. (e.g. ::name::myconnectionstring), or a pointer to an open connection.

      table_or_sql_statement

      The name of the table in the remote database from which to return data. Can either be a table name, or a SQL SELECT statement that retrieves data from one or more tables. If a SQL SELECT statement is specified the result_Expression parameter is meaningless and must be set to a null string.

      filter

      A filter expression to determine which records in the remote table to find. The filter expression must use SQL syntax and must use portable AlphaDAO functions. For example, strings must be single quoted, the AND, OR and NOT operators are not surrounded by periods. The filter expression can use arguments. For example, customerid = :whatcustomerid. If table_or_sql_statement is a SQL SELECT then filter is meaningless and must be set to a null string.

      result_Expression

      A expression to determine what values gets returned. The expression can be as simple as a single column name in the remote table, or it can be a complex expression. The expression must be written using portable AlphaDAO syntax. If table_or_sql_statement is a SQL SELECT then result_Expression  is meaningless and must be set to a null string.

      arguments

      If the filter expression or the SELECT statement in the table_or_sql_statement argument includes arguments, you must supply argument values using a SQL::arguments object.

    • Examples: 

      connection = "{A5API=Access,FileName='C:\northwind2\northwind2003.mdb',UserName='Admin'}"
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "city = 'london'"
? sql_records_get(connection,table,filter,result_expression)
= London - Thomas Hardy
London - Victoria Ashworth
London - Elizabeth Brown
London - Ann Devon
London - Simon Crowther
London - Hari Kumar

'In this example the filter includes an argument
connection = "{A5API=Access,FileName='C:\northwind2\northwind2003.mdb',UserName='Admin'}"
table = "customers"
result_expression = "concatenate(city,' - ',contactname)"
filter = "city = :whatcity"
dim args as sql::arguments
args.set("whatcity","london")
? sql_records_get(connection,table,filter,result_expression,args)
= London - Thomas Hardy
London - Victoria Ashworth
London - Elizabeth Brown
London - Ann Devon
London - Simon Crowther
London - Hari Kumar



'In this example, a complete SQL SELECT statement is used for the 'table' argument.
'Note that CRLFs in the data are returned as \cr\lf. 
'Columns in the data are pipe (e.g.'|') delimited.
'Also, a pointer to an open connection, rather than a connection string, is passed in.
'Since we are passing in an open connection, the function is much faster

dim cn as sql::connection
connection = "{A5API=Access,FileName='C:\northwind2\northwind2003.mdb',UserName='Admin'}"
cn.open(connection)
table = "select customerid, contactname, address from customers where city = 'london'"
result_expression = ""
filter = ""
? sql_records_get(cn,table,filter,result_expression)
= AROUT|Thomas Hardy|120 Hanover Sq.
BSBEV|Victoria Ashworth|Fauntleroy Circus
CONSH|Elizabeth Brown|Berkeley Gardens\cr\lf12 Brewery 
EASTC|Ann Devon|35 King George
NORTS|Simon Crowther|South House\cr\lf300 Queensbridge
SEVES|Hari Kumar|90 Wadhurst Rd.

  • Sql_get_Values() Function

    Can be used to get a list of values from a field in a table in a remote database. Allows you to set a limit on the number of returned values. You can also set a flag to specify that only unique values should be returned. Syntax: c Values = sql_get_values(Connection as A, table as c, filter as c, result_expression as c [, flagDistinct as L [, Limit as n [, flagDescendingOrder as L [, arguments as sql::arguments ]]]])

    • Where:

    • Values

      A CRLF delimited string of data from the remote table or query. CRLFs in the data are encoded as '\cr\lf'.

      connection

      An explicit AlphaDAO connection string, or a named connection string. (e.g. ::name::myconnectionstring), or a pointer to an open connection.

      table

      The name of the table in the remote database from which to return data.

      filter

      A filter expression to determine which records in the remote table to find. The filter expression must use SQL syntax and must use portable AlphaDAO functions. For example, strings must be single quoted, the AND, OR and NOT operators are not surrounded by periods. The filter expression can use arguments. For example, customerid = :whatcustomerid. If table_or_sql_statement is a SQL SELECT then filter is meaningless and must be set to a null string.

      result_Expression

      A expression to determine what values gets returned. The expression can be as simple as a single column name in the remote table, or it can be a complex expression. The expression must be written using portable AlphaDAO syntax.

      flagDistinct

      Default for this if .f.. Specify if only unique values should be returned.

      Limit

      Default for this is 1,000. Specify the maximum number of values to return.

      flagDescendingOrder

      Default for this is .f.. Specify if values should be returned in descending order.

      arguments

      If the filter expression includes arguments, you must supply argument values using a SQL::arguments object.

  • .ServerSideQueryRun() Method

    Applies an incremental filter to an active-link table. The query is executed on the server. Contrast with .Query_Create() which runs a local query. Syntax: N RecordsFound = .ServerSideQueryRun(C filter ,C order [,L additive ])

    • Where:

    • RecordsFound

      Returns the number of records found by the query. If the table is not an active-link table, returns -1. The active-link table does not allow incremental server-side querying, returns -2. For example, an active-link table that was based on a stored procedure would not allow incremental server-side querying.

      filter

      The filter expression. The filter expression must use portable SQL syntax. The filter is in addition to any filter that was defined when the active-link table was defined. For example if the SELECT statement for the active-link table was SELECT * FROM customers WHERE state = 'MA', then the active-link table will always have a base filter of state = 'MA'. I.e. any filter that is specified is in addition to the base filter.

      order

      The order expression. The order expression must use portable SQL syntax.

      additive

      Specifies if the filter should be in addition to any previous server-side filters that were applied.

  • .ServerSideQueryRetract() Method

    Removes the most recently applied server-side filter. Syntax: L Result = .ServerSideQueryRetract()

  • .ServerSideQueryRetractAll() Method

    Removes all of the previously applied server-side incremental filters. Syntax: L Result = .ServerSideQueryRetractAll()

  • .ServerSide_Records_Get() Method

    Gets the number of records in an active-link table. On a large table this will be substantially faster than the .Records_Get() method because .Records_Get() will cause the local record cache to be fully populated ( i.e. every row in the active-link table will be retrieved).

  • .Suggest()

    Returns a list of suggestions from a field or expression in a table. Syntax C Suggestions = .Suggest(C expr,C value [,N limit [, C more_text [, C filter ]]])

    • Expr

      The expression to evaluate to get the suggested values

      Value

      Returns suggestions that start with value.

      Limit

      Number of suggestions to return. -1 (default value), indicates that all suggestions should be returned.

      More_text

      If limit is not -1, then if there are more suggestions than limit, last suggestion contains the more_text text.

      Filter

      Filters the suggestion list.

    • Example

      dim t as p 
t = table.open("customer")
?t.suggest("lastname","s",5)
= Smallwood
Smith
Smith
Smithson

  • .to_sql_expression() Method

    Takes an Xbasic syntax expression and converts it to a SQL expression. If the expression cannot be converted, returns a null string. Syntax: c SQLExpression = .to_sql_expression(C XbaseExpression)

    • Field names from the current active-link table that are referenced in the XbaseExpression are converted to the corresponding SQL expression. Assume that you have an active-link table. The active link table might have (say) two fields: fname and lname. The 'fname' field in the active-link table maps to a field called 'firstname' in the remote table and the 'lname' field map to a field called 'lastname' in the remote table. 

      t = table.open("customers")
?t.to_sql_expression("fname+lname")
= "Firstname+Lastname"

    • In this next example, assume that the active-link table's SQL Select statement is: 

      SELECT firstname, lastname, concatenate(address, ' ', city, '  ', state,' ', zip) as address FROM customers.

    • The active-link table will have three fields: firstname, lastname and address 

      t = table.open("customers")
?t.to_sql_expression("address = '123 main st boston ma 02139'")
= concatenate(address, ' ', city, '  ', state,' ', zip)  = '123 main st boston ma 02130'

    • If the XbaseExpression cannot be converted to a SQL expression, a blank string is returned. Reasons why the conversion might fail include a reference to a function that has no SQL equivalent.

  • .to_sql_filter() Method

    Takes an Xbasic syntax filter expression and converts it to a SQL syntax expression. If the entire filter cannot be converted to SQL, then converts part of the expression to SQL and shows the remainder that is still in Xbasic syntax. Syntax: c filter = .to_sql_filter(C XbaseFilter [, C separator]])

    • If the filter contains multiple clauses, joined with the .AND. operator, then it is possible that some of the clauses can be converted to SQL syntax, while other clauses cannot be converted (typically because they call a function that has no equivalent in the remote database). The separator defines the character string that will be used to separate the part of the filter that can be converted to SQL syntax, and the part that could not be converted. Assume that you have an active-link table on the sample 'customers' table from Northwind. Some of the active-link fieldnames are different than the corresponding fields in the remote table (assume that 'contactname' in the remote table is mapped to 'name' in the active-link table, and that 'region' in the remote table is mapped to 'state_region' in the active-link table). Example: 

      ?t.to_sql_filter("name = \"john smith\" .and. state_region = \"ma\" .and. localUDF(companyname) = \"alpha\"","||")
= ContactName='john smith' and Region='ma'||localUDF(companyname)="alpha"

    • In the above example, only part of the filter could be converted. The separator that was specified was '||', and so the portion that could not be converted is shown after the '||' string. The portion that could not be converted uses a function called 'localUDF()' which presumably does not exist on the remote database, and therefore this part of the filter clause cannot be converted. Note that in the part that is converted the '.and.' operator is changed to 'and' and the double quotes are converted to single quotes.

  • .to_sql_order() Method

    Takes an Xbasic syntax order expression and converts it to a SQL syntax expression. If the order expression cannot be converted, returns a null string. Syntax: c order = .to_sql_order(C XbaseOrder)

    • Assume that you have an active-link table on the sample 'customers' table from Northwind. Some of the active-link fieldnames are different than the corresponding fields in the remote table (assume that 'contactname' in the remote table is mapped to 'name' in the active-link table, and that 'region' in the remote table is mapped to 'state_region' in the active-link table). Example: 

      ?t.to_sql_order("name + state_region")
= "ContactName, Region"

  • UI_Get_Time() Function

    Prompts for a date/time value. Syntax: C time = ui_get_time(C dlgTitle ,C time [,L useCalendarDropdowns [,L connectClockHands [,N hourSnap [,N minuteSnap ]]]])

    • Where:

    • time

      Returns the date time value as a character string. Use ctodt() to convert result to a time value if necessary

      dlgTitle

      The dialog title

      useCanlendarDropdowns

      Specify if month and year are selected from drop down boxes (as shown in the image), or by clicking on the title bar to change the calendar display from days to month, and then from months to years.

      connectClockHands

      If .t., then when you move the minute hand, the hour hand will also move and vice versa. For example, if you move the minute hand (say) by 180 degrees, the hour hand will be positioned between hours. If .f. then moving the minute hand does not cause the hour hand to move. If .f., the hour hand can only snap to full hours (i.e. it can't be positioned between two hours as an analog clock can) .

      hourSnap

      If, for example, hourSnap is set to 15 and connectClockHands is .t., then there will be 4 positions that the minute hand can snap to when the hour hand is moved (e.g. 0, 15 minutes, 30 minutes and 45 minutes after the hour). If connectClockHands is .f. then hourSnap is ignored. The default value for hourSnap is 5 hourSnap can be set to any number between 1 and 60.

      minuteSnap

      When you are moving the minute hand, you can specify what minute interval the hand should snap to. The default value for minuteSnap is 0 (no minute snap).

    • images/What's5.jpg
      Date/time picker displayed by ui_get_time() Function

  • ui_get_short_time() Function

    Prompts for a short time value. Syntax: C shorttime = ui_get_short_time(C dlgTitle ,C time [,L clockConnectHands [,N clockHourSnap [,N clockMinuteSnap [,L clockShowNumericInput ]]]])

    • Where:

    • time

      Returns the short time value as a character string. Use ctot() to convert result to a short time value if necessary

      dlgTitle

      The dialog title

      useCanlendarDropdowns

      Specify if month and year are selected from drop down boxes (as shown in the image), or by clicking on the title bar to change the calendar display from days to month, and then from months to years.

      connectClockHands

      When dragging on the minute hand, does the hour hand move if you drag the minute hand a full revolution (like an analog clock would).

      clockHourSnap

      -

      clockMinuteSnap

      When dragging on minute hand, you can get the minute hand to snap to the closest interval value. I.e. if the clockMinuteSnap is 15, then the minute hand will snap to one of four possible positions.

      clockShowNumericInput

      Specify if a numeric input text box should be shown on the clock.

    • images/What's6.jpg
      Clock displayed by ui_get_short_time()